ContractSpecContractSpec

Start with OSS

Back to changelog index

13.2.0

Jul 17, 2026 · 7 packages · 15 unique changes · 4 release entries

appsbundlesintegrationslibs

This release affects the contracts, integrations, sharedLibs, solutions familyies.

Run contractspec connect adoption resolve --family contracts to see how it impacts your project.

Release summaries

  • companyos-connect-canonicalization-v1

    Add a strict historical-v1 database read boundary so a human can approve forward-only migration 007 before it normalizes text storage to the unchanged public integer-v1 contract, while preserving approval-event provenance across historical JSON-only and complete denormalized storage shapes.

    integrator

    Integrators retain the literal canonicalizationVersion 1 contract while exact historical PostgreSQL text "1" is read compatibly for approval and then normalized by a tracked migration; approval event provenance remains canonical in integrity_metadata before and after denormalization.

    maintainer

    Migration owners get a dry-run-first CLI with advisory locking, predecessor enforcement, transactional rollback, ledger replay, and explicit confirmation. The first-reviewer provisioning apply is intentionally outside the otherwise-circular Connect signature gate, but requires the authenticated migration-owner role, seven exact confirmations, rollback evidence, and idempotent replay. Migration 006a preserves historical ledger IDs while adding reviewer-runtime nonce, issuer, and RLS support; explicit public authorization and reviewer proof metadata replace embedded trust.

  • real-organizations-auth-recovery

    Ship server-authoritative organization and workspace contracts with API/web recovery runtime, and separate authentication readiness from the legacy ND pilot-admission tuple without weakening legacy route admission.

    integrator

    Adopt organization.list, organization.set-active, and workspace.list as additive operations. Use organization.set-active authorityToken for stale-request rejection while retaining authorityVersion as a compatibility field. Continue treating existing tenantId fields as compatibility assertions only. The API and browser adapters now bind these operations with ambient credentials, explicit no-store transport, and canonical authority revalidation.

    maintainer

    Authentication readiness validates auth, database, origin, cookie, and secret prerequisites. Keep the pilot tuple configured for the legacy ND route until persisted organization authority replaces that admission guard. The public composition requires credentialed exact-trusted-origin authority refresh with a private no-store policy, plus one lazy app-owned authority runtime reused until host shutdown. Corrective v1 semantics preserve every distinct provider Set-Cookie, bypass caches for post-write canonical revalidation, recover through membership listing before selection, and atomically audit only actual active-organization transitions. The API, Node response adapter, browser transport, and web switching runtime implement these semantics; live production migration, bootstrap, deployment, and cutover remain separately gated.

  • real-organizations-bootstrap-recovery

    Make the three-organization bootstrap resumable with durable phase receipts and truthful cross-connection interruption semantics.

    integrator

    Bootstrap receipts now expose the stable manifest revision, eight phases, and recovered phases as an additive CompanyOS contract.

    maintainer

    Operators can rerun the same manifest after interruption and must require all eight durable receipts plus three final bindings and grants before cutover.

  • real-organizations-canonical-seeding

    Seed the canonical LSSM, CompanyOS, and NDconsulting organization families from one contract-owned manifest with deterministic replay and redacted evidence.

    integrator

    Adopt the additive organization-seed subpath for exact identities, families, digest versions, expected counts, and redacted receipt DTOs. The existing organization-bootstrap:v1 revision and receipt semantics remain unchanged.

    maintainer

    Run migrate, canonical bootstrap, one manifest-wide seed, and complete verification. Do not supply live tenant/workspace selectors or treat receipt presence alone as replay proof.

    integrator

    Public profile drafts may represent intentionally inactive event metadata with destination mode unavailable; active unavailable events fail validation. Approved hybrid destinations remain HTTPS/Calendly-only.

Deprecations

  • - Existing tenantId fields remain assertion aliases and must not select authorization or RLS scope; derive authority from verified activeOrganizationId, current membership, and the enabled binding.
  • - MANAGED_COMPANYOS_LIVE_SEED_TENANT_ID and MANAGED_COMPANYOS_LIVE_SEED_WORKSPACE_ID are not forward live-seed inputs; the contract manifest owns all organization, tenant, and workspace targets.

Migration guide

  • Adopt the additive organization authority operations

    Use verified session authority for organization and workspace selection.

    1. Enumerate only memberships returned by organization.list.
    2. Await organization.set-active and retain its composite authorityToken for stale-request rejection.
    3. Invalidate organization-scoped caches before loading workspaces.
    4. Call workspace.list without organizationId or tenantId selectors.

  • Keep legacy ND admission fail closed during auth recovery

    Required

    Remove pilot identifiers only from auth readiness, not from the legacy route guard.

    1. Keep MANAGED_COMPANYOS_PILOT_* available to the legacy ND admission resolver.
    2. Verify /api/auth/ok without pilot identifiers.
    3. Verify legacy ND routes still deny when their exact pilot tuple is absent or mismatched.

  • Keep authority responses private and the database runtime app-owned

    Required

    Do not cache organization/workspace projections or create a Postgres pool per request.

    1. Bind organization.list@1.0.0 and organization.set-active@1.0.0 to the declared real API and runtime implementation refs.
    2. Require ambient credentials and exact trusted-origin validation for canonical authority refresh.
    3. Require exact trusted Origin for browser requests and OPTIONS; permit absent Origin only for server transport.
    4. Require Cache-Control private, no-store on every organization and authority projection response, including deny and degraded outcomes.
    5. Propagate every distinct provider Set-Cookie value without coalescing.
    6. Disable authority caches for post-write canonical revalidation and map membership rejection to 403, authority-session drift to 409, and store failure to 503.
    7. Allow membership-list-first recovery when no active organization exists, while granting zero workspace authority until verified selection.
    8. Commit organization.activeChanged through a server-owned database trigger in the active-organization transition; emit no event for the same organization and roll back on audit failure.
    9. Reuse one lazy authority repository and connection pool for the application lifecycle.
    10. Close the app-owned authority runtime during host shutdown.
    11. Run the repository and disposable PostgreSQL atomic-audit proofs before any production migration.

  • Apply migration 0019 before bootstrap

    Required

    Add the migration-owner-only durable phase receipt table.

    1. Apply tracked migrations through 0019.
    2. Keep MANAGED_COMPANYOS_ORG_AUTHORITY_CUTOVER disabled.
    3. Run companyos:bootstrap-admin and require all eight receipts.
    4. If interrupted, rerun the same manifest revision and verify three bindings and grants.

  • Adopt the manifest-wide live seed

    Required

    Seed and verify every declared family after canonical bootstrap.

    1. Apply tracked forward migrations with approval and backup evidence.
    2. Run companyos:bootstrap-admin and require the complete organization-bootstrap:v1 authority manifest.
    3. Run companyos:db:seed:live once without tenant/workspace selectors.
    4. Run companyos:db:verify:live and require exact redacted receipts, counts, semantic digests, and tenant isolation.
    5. Replay twice and require zero duplicate rows, receipts, profile revisions, snapshots, audit rows, or workflow transitions.

  • Apply tracked approval migration 007

    Required

    Validate and denormalize approval-event provenance, then normalize only valid v1 values.

    When: The approval ledger contains migration 006 but not migration 007.

    1. Back up or capture the approval schema and redacted row-count evidence.
    2. Apply tracked migrations through `006a_reviewer_authority_runtime` without changing prior ledger IDs.
    3. Dry-run `contractspec connect review provision-authority` with explicit role, issuer actor, issuer authorization fingerprint, reviewer email, reviewer public-key fingerprint, authority ref, and proof ref; then apply with all seven exact confirmations and require idempotent `existing` replay.
    4. Materialize the exact migration-007 Connect packet against migration 006.
    5. Enroll the human reviewer public key, resolve the signed challenge, and verify replay.
    6. Verify the event schema has either none or all three provenance columns; partial shapes fail closed.
    7. Run `contractspec connect review migrate 007_approval_canonicalization_v1_integer --json` and inspect the dry-run result.
    8. Re-run with `--apply --confirm-migration 007_approval_canonicalization_v1_integer` under the migration-owner database role.
    9. Re-run the apply command and require status `existing` before remaining bootstrap work.

Upgrade steps

  • Deploy the auth readiness correction independently

    manual

    Restore auth health before organization schema or cutover work.

    Packages: @lssm-tech/lib.contracts-spec, @lssm-tech/app.api-application-monolith, @lssm-tech/app.web-application-monolith

    1. Record the immutable deployment digest and git revision.
    2. Verify /api/auth/ok, sign-in, and session establishment.
    3. Verify ND admission remains fail closed and observe zero pilot-readiness 503s for 30 minutes.

  • Prove interruption recovery on real Postgres

    manual

    Run the opt-in Postgres test before production cutover.

    Packages: @lssm-tech/lib.contracts-spec, @lssm-tech/app.api-application-monolith

    1. Set MANAGED_COMPANYOS_TEST_DATABASE_URL to a disposable local Postgres database.
    2. Run scripts/bootstrap-admin-postgres.test.ts.
    3. Confirm the existing credential hash remains unchanged.

  • Verify deterministic replay on disposable PostgreSQL

    manual

    Prove organization atomicity, resumability, drift rejection, and RLS.

    Packages: @lssm-tech/lib.contracts-spec, @lssm-tech/app.api-application-monolith, @lssm-tech/lib.organization-planning-spec

    1. Use PostgreSQL 15 with a NOSUPERUSER NOBYPASSRLS application role.
    2. Apply the full migration chain and a simulated production-through-0017 upgrade path.
    3. Inject a family failure and prove whole-organization rollback while prior organizations remain resumable.
    4. Confirm no OAuth credential, provider mapping, calendar identifier, health row, raw booking URL, or secret appears in receipts or logs.

Unique release changes

  • - Add a strict historical-v1 database read boundary so a human can approve forward-only migration 007 before it normalizes text storage to the unchanged public integer-v1 contract, while preserving approval-event provenance across historical JSON-only and complete denormalized storage shapes.

    4 packages · 4 occurrences

  • - Validate and denormalize approval-event provenance, then normalize only valid v1 values.

    4 packages · 4 occurrences

  • - Do not cache organization/workspace projections or create a Postgres pool per request.

    3 packages · 3 occurrences

  • - Existing tenantId fields remain assertion aliases and must not select authorization or RLS scope; derive authority from verified activeOrganizationId, current membership, and the enabled binding.

    3 packages · 3 occurrences

  • - MANAGED_COMPANYOS_LIVE_SEED_TENANT_ID and MANAGED_COMPANYOS_LIVE_SEED_WORKSPACE_ID are not forward live-seed inputs; the contract manifest owns all organization, tenant, and workspace targets.

    3 packages · 3 occurrences

  • - Prove organization atomicity, resumability, drift rejection, and RLS.

    3 packages · 3 occurrences

  • - Remove pilot identifiers only from auth readiness, not from the legacy route guard.

    3 packages · 3 occurrences

  • - Restore auth health before organization schema or cutover work.

    3 packages · 3 occurrences

  • - Seed and verify every declared family after canonical bootstrap.

    3 packages · 3 occurrences

  • - Seed the canonical LSSM, CompanyOS, and NDconsulting organization families from one contract-owned manifest with deterministic replay and redacted evidence.

    3 packages · 3 occurrences

  • - Ship server-authoritative organization and workspace contracts with API/web recovery runtime, and separate authentication readiness from the legacy ND pilot-admission tuple without weakening legacy route admission.

    3 packages · 3 occurrences

  • - Use verified session authority for organization and workspace selection.

    3 packages · 3 occurrences

  • - Add the migration-owner-only durable phase receipt table.

    2 packages · 2 occurrences

  • - Make the three-organization bootstrap resumable with durable phase receipts and truthful cross-connection interruption semantics.

    2 packages · 2 occurrences

  • - Run the opt-in Postgres test before production cutover.

    2 packages · 2 occurrences

Impacted packages

  • @lssm-tech/app.api-application-monolith

    Layer: apps · 4 changes

  • @lssm-tech/app.cli-contractspec

    Layer: apps · 2 changes

  • @lssm-tech/app.web-application-monolith

    Layer: apps · 6 changes

  • @lssm-tech/bundle.workspace

    Layer: bundles · 2 changes

  • @lssm-tech/integration.runtime

    Layer: integrations · 2 changes

  • @lssm-tech/lib.contracts-spec

    Layer: libs · 2 changes

  • @lssm-tech/lib.organization-planning-spec

    Layer: libs · 4 changes