Files

T

veronica f0d2dd9920 docs(W4): stamp kind and status front matter on 104 live documents

Applies the document contract from
docs/plans/2026-08-20_stack-docs-flatten-and-alignment.md section 3, partially:
`kind` and `status` only. `parent` is deliberately held until the flatten in
section 4 lands, so that 127 documents do not have to be re-pointed by hand
when docs/fleet/NORTH_STAR.yaml moves to docs/NORTH_STAR.yaml.

Scope, measured on origin/next at 63069149:

  127 live docs   = all *.md under docs/ minus docs/archive/ minus docs/_old_structure/
  104 stamped     here
   19 held        operator judgement (plan section 9), worklist in the same PR
    3 held        the SUPERSEDED TASKS.md stamps, which cite the moving path
    1 untouched   docs/fleet/FLEET-DOCTRINE.md, already stamped in W1

Kinds applied: 54 guide, 34 record, 9 spec, 6 tracking, 1 projection.
Every row carries a confidence and a one-line rationale in the worklist.

Two collisions with the existing state, both flagged rather than resolved:

1. docs/README.md:150-160 already documents a front-matter convention
   (title/type/audience/status/source_of_truth) with its own allowed values.
   It is applied to 4 of 127 files. Its `status` vocabulary is
   current|draft|deprecated|historical; the new contract's is active|superseded-by.
   The key collides. This commit lets the new contract win and rewrites
   `status: current` to `status: active` on those 4 files, keeping their other
   legacy keys untouched. No code reads any of them: `git grep source_of_truth`
   outside docs/ returns nothing. docs/README.md still prescribes the old
   convention and is an operator row, so it is not edited here.

2. Two of the plan's 20 operator rows are YAML files, not markdown
   (docs/fleet/examples/roster-v2.yaml, docs/openapi-tess.yaml), and the
   contract's front-matter form has no defined meaning for a .yaml document.
   That gap also applies to docs/fleet/NORTH_STAR.yaml, the source of truth
   itself. Raised in the worklist.

A third row from the plan, docs/fleet/north-star.md, no longer exists: W1
renamed it to docs/fleet/FLEET-DOCTRINE.md.

Verification: 104/104 parse with the expected kind and status in front matter;
the check was shown to reject a wrong kind before it was trusted. The diff
removes 4 lines total, all of them `status: current`.

2026-08-20 19:30:25 -05:00

6.0 KiB

Raw Blame History

kind, status

kind	status
guide	active

Mos Connector Lease Operations — M1

Status: Held / non-operative. Operational authority: None. This page is a future runbook outline, not a current command, endpoint, migration, or activation procedure. Hold condition: The gateway's DenyConnectorLeasePolicy remains the default policy and rejects every lease and grant operation. No connector is activated by this page.

Current state

M1 provides an implemented lease, fencing, audit, and gateway policy boundary. It does not currently provide an operator-facing lease endpoint, activate a connector, cut over a channel, or connect an existing runtime provider to ConnectorExecutionContext. The default gateway module is deny-all, so operators must not treat the schema or internal service as an available lease-control surface.

There is no current operator command sequence to acquire, renew, take over, release, or grant connector authority. Do not attempt to operate the held procedure through direct database writes or by bypassing the gateway policy. Any future activation requires a separately approved server-side policy, concrete adapter, downstream fencing design, and an updated operational runbook.

Held future procedure — not current command authority

The following records the intended shape of a later runbook. It is deliberately non-operative while deny-all remains:

Events and evidence to monitor later

If an authorized policy and adapter are activated in a future work package, correlation IDs may be used to inspect connector_lease_audit_log events:

Event	Meaning
`acquire`	First holder inserted for an unused binding
`renew`	Current holder heartbeat extended the TTL
`takeover`	Authorized compare-and-swap replaced the holder and incremented epoch
`release`	Current holder explicitly relinquished authority
`expiry`	An expired current lease was observed
`reject`	Policy, compare-and-swap, expiry, scope, or fencing validation denied an operation

Audit records are metadata-only. Raw grant objects, connector payloads, scopes, tokens, approval references, and credentials must never be added to audit output. The current schema does not independently enforce append-only storage; database-level protection remains a future hardening requirement.

Held incident-review outline

For a future suspected duplicate or stale connector effect, an approved operator procedure would:

correlate the attempted operation with its reject, takeover, or expiry event;
compare the durable row's connector ID, lease UUID, epoch, expiry, and release time with the adapter's normalized execution context;
treat an old epoch, old lease UUID, expired lease, or released lease as non-authoritative rather than retrying it as the old holder;
use only the authorized takeover path with the observed expected epoch, never ordinary acquire, for an expired or released row; and
preserve evidence without assuming lease fencing provides exactly-once replay safety if an external effect may already have occurred.

These are held review requirements, not instructions to bypass the current deny-all policy.

Held migration and rollback notes

The checked-in 0016_salty_morlocks.sql artifact is additive: it creates the lease and audit tables and indexes without changing existing authorization/session tables. A future database rollout would still require the repository's approved migration, backup, verification, and rollback controls. Application rollback would leave additive lease/audit tables in place; dropping them would destroy evidence and is not an automatic rollback step.

This page does not authorize running migrations, connecting to PostgreSQL, initializing PGlite, or starting a connector. Those activities remain outside this held procedure and subject to repository/runtime gates.

Held security prerequisites

Before this page could become operative, the activation work would need to demonstrate at least:

tenant authority derived from authenticated gateway context, not connector request fields;
authorized policy decisions over normalized identity and scopes, with policy TTL handling based on the requested input and coordinator hard caps still applied;
explicit takeover authorization and expected-epoch compare-and-swap;
application-boundary normalization plus any separately approved database constraints or protections;
validation and rejection audit before adapter side effects;
a concrete adapter that consumes and propagates the normalized epoch/context; and
existing authorization and exact-action approval controls remaining in force.

M1 currently satisfies the boundary contract and default-deny posture, not these activation prerequisites.

Explicit non-goals while held

This page does not authorize or claim:

lease administration from the dashboard, CLI, HTTP, SQL console, or a connector;
production connector or channel activation;
exactly-once delivery, side-effect journaling, checkpoint/handoff recovery, or replay safety;
automatic failover, rollback, or stale-effect recovery across Claude, Pi, Codex, Matrix, tmux, or provider sessions; or
database-enforced audit immutability or database-enforced application normalization.

The page may be promoted to an operative runbook only after deny-all is intentionally replaced, concrete adapters are reviewed, activation evidence exists, and this hold is explicitly removed by the owning work package.

6.0 KiB Raw Blame History