Skip to content

Epic: Implement the kertas.runtime/v1alpha1 ManagedSession contract #31

Description

@wms2537

Context

docs/KERTAS-RUNTIME-CONTRACT.md defines the public Kertas-to-runtime boundary. Current compatibility is run-as-session/v1; the target introduces a real ManagedSession resource without adding Kertas Project state to this repository.

Required outcome

Implement the contract as decomposed, independently reviewed tickets while preserving the current Run API until a documented migration boundary.

Ordered work

  1. Publish machine-readable existing Run API and event schemas — P1: Publish machine-readable existing Run API and event schemas #49; merged by PR Publish existing Run API contract #54; post-merge gate 29898030244 passed
  2. Add compatibility fixtures and contract-version discovery — P1: Add runtime contract discovery and compatibility policy #50; merged by PR Add runtime contract compatibility policy #55; post-merge gate 29898424163 passed
  3. Add ManagedSession storage plus one-active-top-level-Run admission — P1: Implement ManagedSession storage and active-Run admission #51; merged by PR feat: add durable ManagedSessions #56; post-merge gate 29900450072 passed
  4. Add authenticated-source, idempotent inbound events and canonical receipt ordering — P1: Implement idempotent ordered ManagedSession inbound events #52; merged by PR feat: add durable ManagedSession inbound events #57; post-merge gate 29903529410 passed
  5. Add first-class artifacts and bounded child results — closed issues P1: Promote runtime outputs to first-class artifact resources #27 and P1: Return bounded delegated results and queryable lineage #28
  6. Add a Kertas client conformance test against an independently deployed runtime — P1: Prove Kertas client conformance against an independent runtime #53; merged by PR test: prove standalone Kertas runtime conformance #58; post-merge gate 29906593069 passed

Invariants

  • Kertas never imports runtime database or internal modules.
  • Project remains Kertas-owned; ManagedSession/Run/Attempt remain runtime-owned.
  • Duplicate keys/events create one logical effect; conflicting payload reuse fails closed.
  • Run completion does not imply Kertas Outcome satisfaction or Release creation.
  • Project Workspace and runtime workspace transfer only through immutable digested snapshots.
  • Every API/event/checkpoint/artifact format is versioned.

Acceptance criteria

  • each ordered work item has a scoped implementation issue and dependency links
  • current-versus-target compatibility is tested
  • at least one Kertas integration uses only the public contract
  • deprecation/migration policy for run-as-session/v1 is published
  • exact-commit CI and post-merge evidence pass for every implementation slice

Activity

  1. wms2537 commented on Jul 22, 2026

    @wms2537
    CollaboratorAuthor

    ManagedSession contract epic complete. All six slices are merged, each exact-commit and post-merge main gate is recorded above, and PR #58 proves a standalone Kertas client using only the authenticated public runtime contract.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions