up the blokcing tasks

docs/contracts/api-aggregate-2025-12-10.sha256

@@ -0,0 +1 @@
+DDC4CC3145CA66240EF69817FAD26315FFE9AE763466C155AD3EBFCCF10496EB  api-aggregate-2025-12-10.yaml

docs/contracts/api-aggregate-2025-12-10.yaml

@@ -0,0 +1,301 @@
+openapi: 3.1.0
+info:
+  title: StellaOps Aggregate API
+  version: "2025-12-10"
+  description: >
+    Tagged aggregate OpenAPI snapshot for SDK Wave B/C generation.
+    Covers Evidence Locker, timeline events, and metadata surfaces used by CLI,
+    Console, and DevPortal offline bundles. Frozen on 2025-12-10 for reproducible
+    SDK artifacts across TypeScript, Python, Go, and Java.
+servers:
+  - url: https://api.stellaops.local
+    description: Sovereign control plane (staging)
+  - url: https://api.stellaops.example.com
+    description: Sovereign control plane (production)
+security:
+  - bearerAuth: []
+paths:
+  /v1/evidence-locker/bundles:
+    get:
+      summary: List evidence bundles
+      description: Returns evidence bundles ordered by creation time with cursor pagination.
+      parameters:
+        - name: cursor
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Opaque cursor from a prior response; omit for first page.
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 200
+            default: 50
+          description: Page size (max 200).
+      responses:
+        "200":
+          description: Evidence bundle page.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EvidenceBundlePage"
+        "401":
+          $ref: "#/components/responses/UnauthorizedError"
+    post:
+      summary: Create evidence bundle
+      description: >
+        Creates a new evidence bundle from client-supplied artifacts. Server returns a content-addressed
+        bundle identifier and provenance digest for downstream attestations.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/EvidenceBundleRequest"
+      responses:
+        "201":
+          description: Evidence bundle created.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EvidenceBundle"
+        "400":
+          $ref: "#/components/responses/ValidationError"
+        "401":
+          $ref: "#/components/responses/UnauthorizedError"
+  /v1/evidence-locker/bundles/{bundleId}:
+    get:
+      summary: Get evidence bundle
+      parameters:
+        - name: bundleId
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Bundle identifier returned by the create operation.
+      responses:
+        "200":
+          description: Evidence bundle by id.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EvidenceBundle"
+        "401":
+          $ref: "#/components/responses/UnauthorizedError"
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+  /v1/timeline/events:
+    get:
+      summary: List timeline events
+      description: >
+        Returns timeline events with support for source filtering and consistent ordering
+        for replay across offline bundles.
+      parameters:
+        - name: source
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Optional source filter (e.g., scanner, attestor).
+        - name: cursor
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Cursor for pagination.
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 500
+            default: 100
+          description: Page size (max 500).
+      responses:
+        "200":
+          description: Timeline event page.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TimelineEventPage"
+        "401":
+          $ref: "#/components/responses/UnauthorizedError"
+  /v1/sdk/metadata:
+    get:
+      summary: SDK metadata surface
+      description: >
+        Provides deterministic metadata for SDK generation (hash guard, generator version,
+        snapshot tag) to allow clients to verify provenance in offline environments.
+      responses:
+        "200":
+          description: Metadata payload
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SdkMetadata"
+        "401":
+          $ref: "#/components/responses/UnauthorizedError"
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+  schemas:
+    EvidenceBundleRequest:
+      type: object
+      required:
+        - subject
+        - artifacts
+      properties:
+        subject:
+          type: string
+          description: Content-addressed digest of the subject container/image.
+        artifacts:
+          type: array
+          minItems: 1
+          items:
+            $ref: "#/components/schemas/EvidenceItem"
+        annotations:
+          type: object
+          additionalProperties:
+            type: string
+          description: Optional annotations preserved in the bundle manifest.
+    EvidenceItem:
+      type: object
+      required:
+        - type
+        - digest
+      properties:
+        type:
+          type: string
+          description: Evidence type (sbom, attestation, manifest, log).
+        digest:
+          type: string
+          description: Content-addressed digest of the artifact (sha256:...).
+        uri:
+          type: string
+          description: Optional URI to fetch artifact if not inlined.
+    EvidenceBundle:
+      type: object
+      required:
+        - id
+        - createdAt
+        - subject
+        - artifacts
+        - manifestDigest
+      properties:
+        id:
+          type: string
+          description: Bundle identifier.
+        createdAt:
+          type: string
+          format: date-time
+          description: Creation timestamp in UTC.
+        subject:
+          type: string
+          description: Subject digest the bundle binds to.
+        artifacts:
+          type: array
+          items:
+            $ref: "#/components/schemas/EvidenceItem"
+        manifestDigest:
+          type: string
+          description: Digest of the bundle manifest (sha256:...).
+        provenance:
+          type: object
+          description: Optional DSSE statement describing bundle assembly.
+    EvidenceBundlePage:
+      type: object
+      required:
+        - items
+      properties:
+        items:
+          type: array
+          items:
+            $ref: "#/components/schemas/EvidenceBundle"
+        nextCursor:
+          type: string
+          nullable: true
+          description: Opaque cursor for the next page; null when done.
+    TimelineEvent:
+      type: object
+      required:
+        - id
+        - occurredAt
+        - source
+        - type
+      properties:
+        id:
+          type: string
+        occurredAt:
+          type: string
+          format: date-time
+        source:
+          type: string
+        type:
+          type: string
+        data:
+          type: object
+          additionalProperties: true
+    TimelineEventPage:
+      type: object
+      required:
+        - items
+      properties:
+        items:
+          type: array
+          items:
+            $ref: "#/components/schemas/TimelineEvent"
+        nextCursor:
+          type: string
+          nullable: true
+    SdkMetadata:
+      type: object
+      required:
+        - snapshotTag
+        - generatorVersion
+        - snapshotSha256
+      properties:
+        snapshotTag:
+          type: string
+          example: api-aggregate-2025-12-10
+        generatorVersion:
+          type: string
+          example: openapi-generator-cli@7.4.0
+        snapshotSha256:
+          type: string
+          example: sha256:deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef
+    Error:
+      type: object
+      required:
+        - error
+      properties:
+        error:
+          type: string
+        details:
+          type: object
+          additionalProperties: true
+  responses:
+    UnauthorizedError:
+      description: Authentication failed.
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/Error"
+    ValidationError:
+      description: Validation failed.
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/Error"
+    NotFoundError:
+      description: Resource not found.
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/Error"