Feature/osoh push code implementation

docs/governance/OSOH_LEVEL4_PUSH_IMPLEMENTATION_PACKET_DEFINITION.md

@@ -0,0 +1,109 @@
+# OSOH Level 4 — Push Implementation Packet Definition
+
+## Phase Objective
+Define the final implementation handoff packet for the Sentinel push MVP slice before descent into code.
+
+## 4.13 Environment Contract Packet
+Required environment variables:
+- OSOH_SITE_ID
+- OSOH_INGEST_TOKEN
+- OSOH_INGEST_URL
+
+Environment contract rules:
+- all three values are required for push operation
+- missing values fail closed
+- malformed ingest target fails closed
+- site identity must match the registered monitored surface identity
+- environment binding does not imply activation
+
+## 4.14 Secret Boundary Packet
+OSOH_INGEST_TOKEN is server-side only.
+It must not appear in browser-exposed code, client bundles, logs, docs examples with real values, or public runtime surfaces.
+Secret handling remains bounded to telemetry delivery only.
+
+## 4.15 Shared Sender Helper Packet
+A shared sender helper shall:
+- read the required environment values
+- validate presence of required values
+- build the bounded ingest request
+- attach bearer authorization
+- serialize the event payload
+- send telemetry to OSOH ingest
+- fail closed on missing configuration or transport failure
+
+The shared helper does not decide activation, trust, or admission.
+
+## 4.16 Deployment Sender Packet
+The deployment sender shall emit a bounded `deployment` event to OSOH ingest.
+Minimum deployment event payload:
+- deploymentId
+- environment
+- versionOrCommit
+- status
+
+The deployment sender is a telemetry producer only.
+
+## 4.17 Heartbeat Sender Packet
+The heartbeat sender shall emit a bounded `heartbeat` event to OSOH ingest.
+Minimum heartbeat event payload:
+- status
+- summary
+
+The heartbeat sender is a telemetry producer only.
+
+## 4.18 Ingest Request Contract Packet
+The request contract to OSOH ingest shall include:
+- Authorization: Bearer <OSOH_INGEST_TOKEN>
+- content-type: application/json
+
+Request body shape:
+- siteId
+- eventType
+- occurredAt
+- payload
+
+Admissible eventType values for this slice:
+- deployment
+- heartbeat
+
+## 4.19 Push Proof Packet
+The push slice must prove:
+- required environment values are loaded
+- deployment sender can emit a valid event
+- heartbeat sender can emit a valid event
+- OSOH ingest receives the request
+- accepted telemetry is persisted
+- invalid or incomplete events fail closed
+
+## 4.20 Push Slice Done-Definition Packet
+This push slice is done when:
+- environment contract is defined
+- secret boundary is defined
+- shared sender helper contract is defined
+- deployment sender contract is defined
+- heartbeat sender contract is defined
+- ingest request contract is defined
+- push proof expectations are defined
+- all rules remain non-activating and telemetry-only
+
+## 4.21 Governance Return-Check Packet
+After implementation, the slice must be checked against these invariants:
+- Sentinel remains external monitored surface
+- push remains telemetry only
+- credential remains ingest-only
+- activation remains blocked
+- hybrid proof remains required
+- OSOH remains final authority
+
+## 4.22 Descent-Ready Implementation Handoff Packet
+The next authorized lower-level implementation handoff consists of:
+- env wiring implementation
+- shared sender helper implementation
+- deployment sender implementation
+- heartbeat sender implementation
+- proof execution against OSOH ingest
+
+No broader descent is authorized by this phase.
+
+## Phase Completion Marker
+This phase is complete when the full push implementation handoff is explicit, bounded, constitutionally aligned, non-activating, and ready for code descent.

docs/governance/OSOH_LEVEL4_PUSH_MVP_DESIGN_DESCENT.md

@@ -0,0 +1,117 @@
+# OSOH Level 4 — Push MVP Design Descent
+
+## Phase Objective
+Define the full MVP design packet for Sentinel push integration under the already-locked Level 5 constitutional constraints.
+
+## 4.1 Push Event Contract Definition
+The MVP push event contract is limited to two event classes:
+- deployment
+- heartbeat
+
+Required event fields:
+- siteId
+- eventType
+- occurredAt
+- payload
+
+Deployment payload minimum:
+- deploymentId
+- environment
+- version or commit reference
+- status
+
+Heartbeat payload minimum:
+- status
+- summary
+
+No event type outside this bounded MVP set is in scope for this phase.
+
+## 4.2 Identity Binding Design
+Sentinel push events shall bind to one registered monitored surface through OSOH_SITE_ID.
+The site identity used in push events must correspond to the monitored-surface identity already known to OSOH.
+Push identity mismatch must fail closed.
+
+## 4.3 Ingest Credential Scope Design
+Sentinel shall use one ingest-only credential for push delivery.
+The credential shall authorize only event submission into the OSOH ingest path.
+It shall not grant read access, admin capability, control-plane capability, deployment authority, or operator authority.
+
+## 4.4 Ingest Target Wiring Design
+Sentinel shall use OSOH_INGEST_URL as the bounded destination for push telemetry.
+The ingest target must be explicit, environment-supplied, and replaceable without changing the constitutional meaning of the integration.
+If the target is missing or malformed, the sender must fail closed.
+
+## 4.5 Sender Execution Design
+Two sender paths are in scope:
+- deployment sender
+- heartbeat sender
+
+Deployment sender emits a bounded event when a deployment completes or reaches its designated reporting point.
+Heartbeat sender emits a bounded event on a governed recurring basis.
+Both senders act only as telemetry producers.
+
+## 4.6 Secret Handling Design
+Push credentials must remain server-side only.
+Secrets must not be exposed to the browser, client bundles, or user-visible runtime surfaces.
+The MVP design assumes bounded environment-variable handling and non-exposure by default.
+
+## 4.7 Push Validation Design
+The ingest path must validate at minimum:
+- Authorization bearer presence
+- token-to-site binding
+- active/inactive handling under fail-closed logic
+- event type admissibility
+- occurredAt format validity
+- payload structural presence
+- site identity coherence
+
+Invalid or inconsistent events must be rejected without trust-presuming fallback.
+
+## 4.8 Telemetry Persistence Design
+Accepted push events must be persisted as monitored-surface telemetry evidence.
+Persistence must preserve:
+- site identity
+- event type
+- receipt time
+- occurrence time
+- bounded payload
+- audit trace of acceptance or rejection
+
+This persistence serves monitoring evidence only, not trust transfer.
+
+## 4.9 Non-Activation Boundary Design
+Implementation of push senders, secrets, env wiring, and event persistence does not activate Sentinel.
+Activation remains blocked until future hybrid pull-plus-push verification is completed under OSOH authority.
+
+## 4.10 Proof-Of-Entry Design
+The push MVP slice must be able to prove:
+- Sentinel emitted a bounded push event
+- the event reached OSOH ingest
+- the event was validated under bounded rules
+- the accepted event was persisted
+- the event remained telemetry only
+
+## 4.11 Governance Return-Check Design
+After implementation, the slice must be checked back against Level 5 invariants:
+- Sentinel remains external
+- push remains telemetry only
+- credential remains ingest-only
+- fail-closed handling remains intact
+- hybrid requirement remains intact
+- OSOH remains final authority
+
+## 4.12 MVP Completion Gate For Push Slice
+The push MVP design slice is complete when:
+- deployment sender is designed
+- heartbeat sender is designed
+- OSOH_SITE_ID binding is defined
+- OSOH_INGEST_TOKEN handling is defined
+- OSOH_INGEST_URL wiring is defined
+- validation expectations are defined
+- persistence expectations are defined
+- non-activation boundary is explicit
+- proof-of-entry expectation is explicit
+- governance return-check is explicit
+
+## Phase Completion Marker
+This phase is complete when the full push MVP design is explicitly bounded, constitutionally aligned, non-activating, proof-oriented, and ready for lower-level implementation descent.

docs/governance/OSOH_PUSH_GOVERNANCE_PHASE_MANIFEST.md

@@ -0,0 +1,25 @@
+# OSOH Push Governance Phase Manifest
+
+## Completed Level 5 Push Governance Files
+- OSOH_SENTINEL_PUSH_CONSTITUTIONAL_ADMISSION.md
+- OSOH_SENTINEL_PUSH_CONSTITUTIONAL_RULE_MATRIX.md
+- OSOH_SENTINEL_PUSH_ACCEPTANCE_CONDITIONS.md
+- OSOH_SENTINEL_PUSH_ACTIVATION_BOUNDARY_CONDITIONS.md
+- OSOH_SENTINEL_PUSH_CONSTITUTIONAL_COMPLETION_CRITERIA.md
+- OSOH_PUSH_GOVERNANCE_TO_MVP_BRIDGE.md
+- OSOH_PUSH_GOVERNANCE_TO_MVP_BRIDGE_DONE_DEFINITION.md
+- OSOH_PUSH_IMPLEMENTATION_DESCENT_AUTHORITY.md
+- OSOH_PUSH_IMPLEMENTATION_DESCENT_AUTHORITY_DONE_DEFINITION.md
+- OSOH_PUSH_DESCENT_EXIT_CRITERIA.md
+- OSOH_PUSH_DESCENT_EXIT_CRITERIA_DONE_DEFINITION.md
+- OSOH_PUSH_DESCENT_READINESS_GATE.md
+- OSOH_PUSH_DESCENT_READINESS_GATE_DONE_DEFINITION.md
+
+## Phase Status
+Level 5 push governance is complete and merged to main.
+
+## Next Boundary
+No further descent is authorized unless explicitly requested by the user.
+
+## MVP Stop Condition
+All future work remains bounded by: reach MVP and stop.

package.json

@@ -13,7 +13,9 @@
     "prepare": "husky",
     "gates": "powershell -ExecutionPolicy Bypass -File .\\scripts\\l6-gates.ps1",
     "prepush": "npm run build && npm run gates",
-    "docs:gate": "powershell -ExecutionPolicy Bypass -File .\\scripts\\docs-gate.ps1"
+    "docs:gate": "powershell -ExecutionPolicy Bypass -File .\\scripts\\docs-gate.ps1",
+    "osoh:push:deployment": "tsx scripts/osoh-send-deployment.ts",
+    "osoh:push:heartbeat": "tsx scripts/osoh-send-heartbeat.ts"
   },
   "dependencies": {
     "@astrojs/check": "^0.9.0",
@@ -41,6 +43,7 @@
     "@testing-library/jest-dom": "^6.9.1",
     "husky": "^9.1.7",
     "jsdom": "^28.1.0",
+    "tsx": "^4.21.0",
     "vitest": "^4.0.18"
   }
 }

scripts/osoh-send-deployment.ts

@@ -0,0 +1,29 @@
+import { sendOsohPushEvent, readOsohPushEnv } from '../src/lib/server/osoh-push-client';
+
+async function main(): Promise<void> {
+  const env = readOsohPushEnv();
+
+  const response = await sendOsohPushEvent({
+    siteId: env.siteId,
+    eventType: 'deployment',
+    occurredAt: new Date().toISOString(),
+    payload: {
+      deploymentId: process.env.OSOH_DEPLOYMENT_ID ?? `deploy_${Date.now()}`,
+      environment: process.env.OSOH_DEPLOY_ENV ?? 'unknown',
+      versionOrCommit: process.env.OSOH_VERSION_OR_COMMIT ?? 'unknown',
+      status: process.env.OSOH_DEPLOY_STATUS ?? 'completed'
+    }
+  });
+
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(`Deployment push failed: ${response.status} ${body}`);
+  }
+
+  console.log('deployment push ok');
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exit(1);
+});