@wrongstack/governance 0.298.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ECOSTACK TECHNOLOGY OÜ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,172 @@
+# @wrongstack/governance
+
+Deterministic workflow vocabulary and transition policy for WrongStack.
+
+This package deliberately has no provider, agent, tool, or UI dependency. Its deterministic core is wrapped
+by isolated SQLite and local IPC adapters. Models remain the primary reasoning and execution resource: they
+can propose plans, transitions, retries, replans, and completion. The transition engine decides whether a
+proposal is inside the approved autonomy envelope and can therefore proceed automatically.
+
+The package is not connected to the current runtime yet. Existing Agent, Director, Kanban, SDD, Goal,
+and MCP behavior remains unchanged while the governance contract is introduced incrementally.
+
+`TaskContractV1` defines requirements, acceptance criteria, evidence expectations, review dimensions,
+rollback class, path scope, change budgets, and an A0-A4 autonomy envelope. Low-risk work can proceed
+without human prompts; sensitive operations can be explicitly escalated or narrowly pre-authorized by
+project policy.
+
+`PlanVersionV1` stores immutable model-generated plan content as a requirement-linked DAG. Replanning
+creates a parent-linked next version instead of rewriting history. Step-level autonomy classification
+keeps ordinary implementation and verification automatic while isolating only the sensitive steps that
+need escalation.
+
+The pure task aggregate accepts command envelopes, evaluates trusted deterministic facts outside model
+arguments, emits one immutable event proposal, and rebuilds state by deterministic replay. Persistence,
+daemon ownership, and runtime adapters remain separate from model execution.
+
+`SqliteGovernanceEventStore` is an isolated append-only persistence adapter. It commits an accepted event
+and its command receipt in one `BEGIN IMMEDIATE` transaction, records rejected decisions for stable retry
+semantics, rejects reuse of a command id with a different payload, and reconstructs historical results by
+event replay. Trusted decision facts are stored with the receipt for auditability. Production runtime code
+does not open this database yet; the opt-in project daemon remains the only process allowed to own it.
+
+`GovernanceProjectService` adds a transport-neutral, project-scoped owner with explicit `task_read`,
+`audit_read`, `command_submit`, and `shadow_observe` capabilities. Capabilities are supplied by trusted
+server context rather than request payloads. Trusted transition facts are resolved by a service-owned policy
+provider and are structurally absent from model command requests. The typed service core is not itself a
+network security boundary; credential binding, unknown-input decoding, IPC election, and process lifecycle
+are enforced by the surrounding local server and daemon adapters.
+
+`decodeGovernanceServiceRequest` is the mandatory future wire boundary for unknown JSON. It rejects unknown
+fields at every governed schema level, validates command/contract/plan/observation shapes, applies bounded
+JSON depth and collection limits, and returns a deeply frozen request. Capability and trusted decision-fact
+fields are absent from the accepted wire schema and are rejected if injected.
+
+`LegacyGovernanceShadowAdapter` has only `shadow_observe`. It writes idempotent legacy observations to a
+separate append-only ledger and cannot submit governance commands or transition canonical task state. This
+allows compatibility telemetry before any legacy workflow is blocked or replaced.
+
+`GovernanceCapabilityGrantRegistry` issues short-lived opaque grants bound to one project and client. Only a
+SHA-256 verifier is retained; raw bearer tokens are returned once, expire inclusively, can be revoked, and
+are intentionally lost when the future daemon restarts. `AuthenticatedGovernanceProjectService` resolves a
+valid grant into an immutable capability set before calling the internal service. The legacy shadow adapter
+uses this authenticated facade instead of constructing its own capabilities.
+
+The ephemeral registry is bounded by `maxGrants`. It emits immutable lifecycle records through an injected
+audit sink instead of retaining an unbounded in-memory history; the project server appends those records to
+the persistent evidence ledger.
+
+`GovernanceProjectServer` and `GovernanceProjectClient` provide a local IPC skeleton for isolated testing.
+The server binds the deterministic per-project endpoint before opening `.wrongstack/governance/governance.sqlite`,
+so a losing owner never opens a second database connection. Credentials travel in a strict transport
+envelope, separate from the inner request, and only the authenticated facade receives decoded calls. Frames,
+connections, and half-open socket lifetimes are bounded. Capability lifecycle observations require
+`audit_read`; ordinary task readers cannot see them, and shadow writers cannot forge reserved audit events.
+
+`launchGovernanceProjectDaemon` is an explicit, opt-in detached-process boundary. The built daemon acquires
+the endpoint before SQLite, then returns one initial client grant over the private parent-child IPC channel.
+The raw token is never placed in argv, inherited environment, or a bootstrap file. The daemon inherits only
+a small operating-system environment allowlist, rejects unknown handshake fields, validates project/client
+identity, and exits instead of silently falling back to a second in-process owner. A competing launch reports
+`owner_conflict` without disturbing the current owner.
+
+The daemon publishes strict, secrets-free liveness metadata under `.wrongstack/governance/daemon.json`:
+protocol and schema versions, canonical project identity, endpoint, PID, instance id, and start time. It does
+not persist bearer tokens, client credentials, or capabilities. Metadata is a discovery hint rather than an
+ownership authority: endpoint binding remains authoritative, and the launcher verifies the on-disk instance
+identity before returning a bootstrap credential.
+
+`connectGovernanceProjectClient` is a non-starting discovery adapter for callers that already hold an
+ephemeral credential. It requires live metadata, matching project identity, and a successful authenticated
+health response before returning a client. Missing or contradictory state is returned as an explicit result;
+the helper neither launches a daemon nor reads or writes credential material.
+
+Daemon startup is serialized by an atomically created project-local lease. A lease held by a live PID is never
+removed, malformed lease data fails loud, and release removes only the exact record owned by that instance.
+After a failed endpoint probe, a dead or missing owner permits stale filesystem-socket cleanup only while the
+lease is held on Unix-like platforms. Windows named pipes are not deleted; contradictory owner/endpoint state
+fails with `endpoint_invalid` instead of guessing. An abrupt Windows process stop can leave stale metadata,
+which the next launch treats as a dead liveness hint and replaces only after it has acquired the endpoint.
+
+An explicitly bootstrapped `capability_admin` client can issue short-lived ordinary-client grants, list public
+grant metadata in cursor pages of at most 100 records, rotate active credentials, and revoke grants through the
+authenticated facade. Rotation preserves the target client and exact capability set, replaces the old verifier
+only after one append-only `grant_rotated` audit event succeeds, and never places the replacement token in the
+audit ledger. An administrator can rotate only its own `capability_admin` grant and cannot delegate that
+capability.
+The facade derives `issuedBy` from the authenticated administrator rather than request data, and lifecycle
+events are appended to the audit ledger without storing the returned bearer token. Ordinary model clients
+cannot call grant-management operations unless a trusted launcher deliberately gave them the admin grant.
+
+Daemon lifecycle control is a separate `daemon_control` capability; `capability_admin` alone cannot inspect
+or stop the owner process. Like `capability_admin`, it can be bootstrapped only through the trusted launcher
+and cannot be delegated by a service request. Status reports the live PID, instance id, project id, and start
+time from the daemon-owned adapter. Shutdown requests must name the expected instance id, derive the requester
+from the authenticated grant, and append a reserved `daemon_shutdown_requested` audit observation before
+acceptance. The server half-closes the client socket with the complete response and invokes the daemon stop
+callback only after that response is flushed; an audit failure or stale instance id leaves the daemon running.
+Shadow/model observations cannot forge the reserved `daemon_*` evidence namespace.
+
+Successful grant issue, rotation, and revocation mutations reserve a bounded in-memory retry receipt before
+changing registry state. Reusing the same administrator credential, `requestId`, and canonical payload within
+30 seconds replays the exact response instead of repeating the mutation; reusing the id with another payload
+is rejected. This also lets a self-rotating administrator recover its replacement credential with only the exact
+old request. Receipt capacity fails before mutation, entries expire without timers, and the cache is cleared on
+shutdown. Replacement tokens may exist in this bounded process memory during the retry window but are never
+written to daemon metadata, SQLite, argv, environment variables, or audit observations. This is daemon-lifetime
+network retry protection, not durable replay across a process restart.
+
+`GovernanceCredentialLeaseController` is an opt-in process-local holder for one self-rotating
+`capability_admin` credential. It schedules renewal before expiry, reuses one request id across a bounded
+three-attempt retry cycle, swaps its internal IPC client only after strict replacement identity validation,
+and serializes ordinary requests behind an in-flight rotation. The controller never exposes the current token
+in its snapshot. Retry exhaustion and expiry are terminal, observable states rather than unbounded healing
+loops; configured timeout and retry windows must fit inside the server's retry-receipt TTL. Failure text is
+bounded and credential-shaped values are redacted. Its referenced scheduler exists only after a trusted caller
+explicitly creates and starts the controller, and `stop()` cancels the pending timer without revoking the
+still-valid grant.
+
+`connectGovernanceAdminSessionFromLaunch` and `connectGovernanceAdminSession` compose daemon discovery,
+authenticated health, public self-grant inspection, and the lease controller for a trusted control-plane
+holder. A session is created only when project, daemon instance, grant, client, expiry, and
+`capability_admin` identity agree. `read_own_capability_grant` reveals only the authenticated caller's public
+grant descriptor and never its token. Session snapshots contain daemon and lease status but no credential.
+This admin session must not be passed to a model-facing tool surface; ordinary agents should receive narrowly
+scoped child grants. Session `readDaemonStatus()` and `shutdownDaemon()` require a separately bootstrapped
+`daemon_control` grant. `shutdownDaemon()` binds the request to the verified session metadata and stops lease
+renewal only after the acceptance response arrives. Session `stop()` stops renewal only—it does not terminate
+the detached project daemon or revoke the current grant.
+
+`prepareGovernanceCompatibilityRuntime` is an opt-in compatibility factory for gradual runtime adoption. It
+attaches only when the trusted caller supplies an existing admin grant, otherwise inspects ownership and
+launches a new daemon only when the project has no live owner. A live owner without an explicit credential,
+invalid metadata, launch failure, or provisioning failure returns a structured `mode: "legacy"` result; the
+factory never steals the endpoint or silently creates an in-process authority. The current WrongStack runtime
+decides whether to continue through its existing path after observing that result.
+
+On success the factory uses the admin session to issue one explicit, short-lived model grant. The caller must
+choose the model capabilities; `capability_admin` and `daemon_control` are rejected before inspection or
+process launch. The returned runtime exposes a `GovernanceModelSession` whose IPC client is held in a native
+private field, while daemon control remains in the trusted runtime wrapper. Model requests are still autonomous
+within their assigned capabilities and remain subject to deterministic server checks. `close()` revokes the
+model grant before stopping the admin lease, and `shutdownDaemon()` revokes it before requesting identity-bound
+daemon shutdown. If a newly launched daemon cannot finish model provisioning, the factory requests graceful
+rollback; it never shuts down an owner to which it merely attached. Snapshots and fallback results contain no
+bearer credentials.
+
+The interactive CLI now has one experimental, default-off compatibility callsite. Setting
+`WRONGSTACK_GOVERNANCE=1` after session creation dynamically loads
+`@wrongstack/runtime/governance-bootstrap`; every other value leaves the governance runtime chunk unloaded and
+the existing execution path unchanged. Successful bootstrap publishes only a credential-free snapshot into
+session metadata. Structured fallback or unexpected bootstrap failure is logged and the legacy runtime
+continues. The LLM still uses the existing WrongStack executor and tools in this phase; its governance model
+session is provisioned with `task_read`, `command_submit`, and `shadow_observe` but is not yet the tool-execution
+path. A daemon launched by this compatibility session is shut down when the session ends, while an attached
+owner is only detached. This session-scoped policy avoids trapping later sessions until durable admin
+credential handoff exists.
+
+There is still no default-on runtime spawn, idle policy, durable credential discovery, cross-process token
+handoff, or governance-backed tool gateway in a legacy execution callsite.
+The detached daemon currently uses the service's conservative default decision context; a trusted policy
+adapter must be installed before command execution is enabled for production callers. Existing WrongStack
+execution continues unchanged.

package/dist/admin-session.d.ts

@@ -0,0 +1,56 @@
+import type { GovernanceServiceCredential } from './capability-grant.js';
+import { GovernanceCredentialLeaseController, type GovernanceCredentialLeaseSnapshot } from './credential-lease-controller.js';
+import type { GovernanceProjectDaemonLaunch } from './daemon-launcher.js';
+import type { GovernanceDaemonMetadata } from './daemon-metadata.js';
+import { type GovernanceProjectClientOptions } from './project-client.js';
+import type { GovernanceServiceResponse } from './project-service.js';
+export interface GovernanceAdminSessionLeaseOptions extends GovernanceProjectClientOptions {
+    readonly rotationTtlMs?: number | undefined;
+    readonly renewBeforeMs?: number | undefined;
+    readonly retryDelayMs?: number | undefined;
+    readonly maxAttempts?: number | undefined;
+    readonly startLease?: boolean | undefined;
+}
+export interface ConnectGovernanceAdminSessionOptions extends GovernanceAdminSessionLeaseOptions {
+    readonly projectRoot: string;
+    readonly projectId: string;
+    readonly grantId: string;
+    readonly credential: GovernanceServiceCredential;
+}
+export type GovernanceAdminSessionConnectionFailureCode = 'not_running' | 'endpoint_invalid' | 'project_mismatch' | 'credential_mismatch' | 'authentication_failed' | 'service_rejected' | 'admin_required' | 'grant_mismatch';
+export type ConnectGovernanceAdminSessionResult = {
+    readonly connected: true;
+    readonly session: GovernanceAdminSession;
+} | {
+    readonly connected: false;
+    readonly code: GovernanceAdminSessionConnectionFailureCode;
+    readonly message: string;
+};
+export interface GovernanceAdminSessionSnapshot {
+    readonly mode: 'attached' | 'launched';
+    readonly daemon: {
+        readonly projectRoot: string;
+        readonly projectId: string;
+        readonly pid: number;
+        readonly instanceId: string;
+        readonly startedAt: string;
+    };
+    readonly lease: GovernanceCredentialLeaseSnapshot;
+}
+declare const GOVERNANCE_ADMIN_SESSION_CONSTRUCTION: unique symbol;
+export declare class GovernanceAdminSession {
+    readonly mode: 'attached' | 'launched';
+    private readonly metadata;
+    private readonly lease;
+    constructor(construction: typeof GOVERNANCE_ADMIN_SESSION_CONSTRUCTION, mode: 'attached' | 'launched', metadata: GovernanceDaemonMetadata, lease: GovernanceCredentialLeaseController);
+    request(input: unknown): Promise<GovernanceServiceResponse>;
+    readDaemonStatus(): Promise<GovernanceServiceResponse>;
+    shutdownDaemon(reason?: string): Promise<GovernanceServiceResponse>;
+    rotateNow(): Promise<GovernanceCredentialLeaseSnapshot>;
+    stop(): GovernanceAdminSessionSnapshot;
+    snapshot(): GovernanceAdminSessionSnapshot;
+}
+export declare function connectGovernanceAdminSession(options: ConnectGovernanceAdminSessionOptions): Promise<ConnectGovernanceAdminSessionResult>;
+export declare function connectGovernanceAdminSessionFromLaunch(launch: GovernanceProjectDaemonLaunch, options?: GovernanceAdminSessionLeaseOptions): Promise<ConnectGovernanceAdminSessionResult>;
+export {};
+//# sourceMappingURL=admin-session.d.ts.map

package/dist/attachment-broker-controller.d.ts

@@ -0,0 +1,73 @@
+import type { IssuedGovernanceCapabilityGrant, IssueGovernanceCapabilityGrantOptions } from './capability-grant.js';
+import { type GovernanceDaemonAttachmentBrokerRecord, type GovernanceDaemonMetadata } from './daemon-metadata.js';
+export declare const GOVERNANCE_DAEMON_ATTACHMENT_BROKER_RENEW_BEFORE_MS: number;
+export declare const GOVERNANCE_DAEMON_ATTACHMENT_BROKER_RETRY_MS = 5000;
+export declare const GOVERNANCE_DAEMON_ATTACHMENT_BROKER_DEGRADED_FAILURES = 3;
+export type GovernanceAttachmentBrokerLifecycleEventType = 'published' | 'renewal_failed' | 'degraded' | 'revocation_failed' | 'recovered' | 'stopped';
+export interface GovernanceAttachmentBrokerLifecycleEvent {
+    readonly schemaVersion: 1;
+    readonly sequence: number;
+    readonly type: GovernanceAttachmentBrokerLifecycleEventType;
+    readonly projectId: string;
+    readonly instanceId: string;
+    readonly occurredAt: string;
+    readonly state: GovernanceAttachmentBrokerControllerSnapshot['state'];
+    readonly health: GovernanceAttachmentBrokerControllerSnapshot['health'];
+    readonly grantId: string | null;
+    readonly expiresAt: string | null;
+    readonly consecutiveFailures: number;
+    readonly pendingRevocations: number;
+    readonly message?: string | undefined;
+}
+export interface GovernanceAttachmentBrokerScheduler {
+    schedule(callback: () => void, delayMs: number): unknown;
+    cancel(handle: unknown): void;
+}
+export interface GovernanceAttachmentBrokerControllerSnapshot {
+    readonly state: 'idle' | 'active' | 'retry_wait' | 'stopped';
+    readonly health: 'initializing' | 'healthy' | 'degraded' | 'stopped';
+    readonly grantId: string | null;
+    readonly expiresAt: string | null;
+    readonly consecutiveFailures: number;
+    readonly pendingRevocations: number;
+    readonly auditHealthy: boolean;
+    readonly nextActionAt?: string | undefined;
+    readonly lastFailure?: string | undefined;
+    readonly lastAuditFailure?: string | undefined;
+}
+interface GovernanceAttachmentBrokerGrantPort {
+    issueGrant(options: IssueGovernanceCapabilityGrantOptions): IssuedGovernanceCapabilityGrant;
+    revokeGrant(grantId: string, reason?: string): boolean;
+}
+export interface GovernanceAttachmentBrokerControllerOptions {
+    readonly projectRoot: string;
+    readonly metadata: GovernanceDaemonMetadata;
+    readonly grants: GovernanceAttachmentBrokerGrantPort;
+    readonly ttlMs?: number | undefined;
+    readonly renewBeforeMs?: number | undefined;
+    readonly retryMs?: number | undefined;
+    readonly degradedFailureThreshold?: number | undefined;
+    readonly now?: (() => number) | undefined;
+    readonly scheduler?: GovernanceAttachmentBrokerScheduler | undefined;
+    readonly publish?: ((broker: GovernanceDaemonAttachmentBrokerRecord) => Promise<void>) | undefined;
+    readonly remove?: (() => Promise<boolean>) | undefined;
+    readonly onEvent?: ((event: GovernanceAttachmentBrokerLifecycleEvent) => void) | undefined;
+}
+export declare class GovernanceAttachmentBrokerController {
+    #private;
+    constructor(options: GovernanceAttachmentBrokerControllerOptions);
+    start(): Promise<GovernanceDaemonAttachmentBrokerRecord>;
+    rotateNow(): Promise<GovernanceDaemonAttachmentBrokerRecord>;
+    stop(): Promise<GovernanceAttachmentBrokerControllerSnapshot>;
+    snapshot(): GovernanceAttachmentBrokerControllerSnapshot;
+    private rotateOnce;
+    private publish;
+    private remove;
+    private revokePending;
+    private health;
+    private emit;
+    private schedule;
+    private cancelTimer;
+}
+export {};
+//# sourceMappingURL=attachment-broker-controller.d.ts.map

package/dist/authenticated-project-service.d.ts

@@ -0,0 +1,18 @@
+import type { GovernanceCapabilityGrantRegistry, GovernanceServiceCredential } from './capability-grant.js';
+import type { GovernanceDaemonControlPort } from './daemon-control.js';
+import { GovernanceManagementReceiptCache } from './management-receipt-cache.js';
+import type { GovernanceProjectService, GovernanceServiceResponse } from './project-service.js';
+export declare const GOVERNANCE_RUNTIME_ATTACHMENT_MAX_TTL_MS: number;
+/** External facade for a future IPC transport. Raw capability sets never cross this boundary. */
+export declare class AuthenticatedGovernanceProjectService {
+    #private;
+    private readonly service;
+    private readonly grants;
+    private readonly receipts;
+    private readonly daemonControl?;
+    readonly projectId: string;
+    constructor(service: GovernanceProjectService, grants: GovernanceCapabilityGrantRegistry, receipts?: GovernanceManagementReceiptCache, daemonControl?: GovernanceDaemonControlPort | undefined);
+    handleUnknown(input: unknown, credential: GovernanceServiceCredential): GovernanceServiceResponse;
+    close(): void;
+}
+//# sourceMappingURL=authenticated-project-service.d.ts.map

package/dist/autonomy-envelope.d.ts

@@ -0,0 +1,40 @@
+export declare const AUTONOMY_TIERS: readonly ['A0', 'A1', 'A2', 'A3', 'A4'];
+export type AutonomyTier = (typeof AUTONOMY_TIERS)[number];
+export declare const GOVERNED_OPERATIONS: readonly ['repository_read', 'file_edit', 'focused_check', 'shell_restricted', 'subagent_spawn', 'git_local_write', 'shell_arbitrary', 'package_install', 'public_api_change', 'schema_change', 'network_access', 'secret_access', 'git_push', 'publish', 'deploy', 'destructive_external'];
+export type GovernedOperation = (typeof GOVERNED_OPERATIONS)[number];
+export interface ChangeBudget {
+    readonly maxChangedFiles: number;
+    readonly maxChangedLines: number;
+    readonly maxNewDependencies: number;
+    readonly maxRetries: number;
+    readonly maxReplans: number;
+    readonly maxSubagents: number;
+    readonly maxWallClockMs: number;
+}
+export interface AutonomyEnvelope {
+    readonly tier: AutonomyTier;
+    readonly allowedOperations: readonly GovernedOperation[];
+    readonly humanApprovalRequiredFor: readonly GovernedOperation[];
+    readonly allowedPaths: readonly string[];
+    readonly deniedPaths: readonly string[];
+    readonly budget: ChangeBudget;
+    readonly autoAuthorizePlan: boolean;
+    readonly autoReplanLimit: number;
+    readonly autoResolveReviewFixes: boolean;
+}
+export type OperationAutonomyDecision = {
+    readonly allowed: true;
+    readonly requiresHumanApproval: false;
+    readonly operation: GovernedOperation;
+    readonly minimumTier: AutonomyTier;
+} | {
+    readonly allowed: false;
+    readonly requiresHumanApproval: true;
+    readonly operation: GovernedOperation;
+    readonly minimumTier: AutonomyTier;
+    readonly reason: 'operation_not_allowed' | 'explicit_approval_required' | 'tier_exceeded';
+};
+export declare const OPERATION_MINIMUM_TIER: Readonly<Record<GovernedOperation, AutonomyTier>>;
+export declare function compareAutonomyTiers(left: AutonomyTier, right: AutonomyTier): number;
+export declare function decideOperationAutonomy(envelope: AutonomyEnvelope, operation: GovernedOperation): OperationAutonomyDecision;
+//# sourceMappingURL=autonomy-envelope.d.ts.map

package/dist/capability-grant.d.ts

@@ -0,0 +1,122 @@
+import { type GovernanceServiceCapability, type GovernanceServiceClientContext } from './service-protocol.js';
+export declare const DEFAULT_GOVERNANCE_GRANT_MAX_TTL_MS: number;
+export declare const DEFAULT_GOVERNANCE_MAX_GRANTS = 10000;
+export type GovernanceCapabilityGrantStatus = 'active' | 'expired' | 'revoked';
+export interface GovernanceCapabilityGrant {
+    readonly grantId: string;
+    readonly projectId: string;
+    readonly clientId: string;
+    readonly issuedBy: string;
+    readonly capabilities: readonly GovernanceServiceCapability[];
+    readonly issuedAt: string;
+    readonly expiresAt: string;
+    readonly status: GovernanceCapabilityGrantStatus;
+    readonly revokedAt?: string | undefined;
+    readonly revokedBy?: string | undefined;
+    readonly revocationReason?: string | undefined;
+}
+export interface IssuedGovernanceCapabilityGrant {
+    readonly token: string;
+    readonly grant: GovernanceCapabilityGrant;
+}
+export interface IssueGovernanceCapabilityGrantOptions {
+    readonly clientId: string;
+    readonly issuedBy?: string | undefined;
+    readonly capabilities: readonly GovernanceServiceCapability[];
+    readonly ttlMs: number;
+}
+export interface RotateGovernanceCapabilityGrantOptions {
+    readonly rotatedBy?: string | undefined;
+    readonly ttlMs: number;
+    readonly reason?: string | undefined;
+}
+export interface GovernanceServiceCredential {
+    readonly token: string;
+    readonly projectId: string;
+    readonly clientId: string;
+}
+export type GovernanceCapabilityAuthenticationFailureCode = 'invalid_token' | 'project_mismatch' | 'client_mismatch' | 'grant_expired' | 'grant_revoked';
+export type GovernanceCapabilityAuthenticationResult = {
+    readonly authenticated: true;
+    readonly grant: GovernanceCapabilityGrant;
+    readonly client: GovernanceServiceClientContext;
+} | {
+    readonly authenticated: false;
+    readonly code: GovernanceCapabilityAuthenticationFailureCode;
+    readonly message: string;
+};
+export type GovernanceGrantAuditEvent = {
+    readonly sequence: number;
+    readonly type: 'grant_issued';
+    readonly grantId: string;
+    readonly projectId: string;
+    readonly clientId: string;
+    readonly issuedBy: string;
+    readonly capabilities: readonly GovernanceServiceCapability[];
+    readonly occurredAt: string;
+    readonly expiresAt: string;
+} | {
+    readonly sequence: number;
+    readonly type: 'grant_revoked';
+    readonly grantId: string;
+    readonly projectId: string;
+    readonly clientId: string;
+    readonly revokedBy: string;
+    readonly occurredAt: string;
+    readonly reason: string;
+} | {
+    readonly sequence: number;
+    readonly type: 'grant_expired';
+    readonly grantId: string;
+    readonly projectId: string;
+    readonly clientId: string;
+    readonly occurredAt: string;
+    readonly reason: string;
+} | {
+    readonly sequence: number;
+    readonly type: 'grant_rotated';
+    readonly grantId: string;
+    readonly previousGrantId: string;
+    readonly projectId: string;
+    readonly clientId: string;
+    readonly rotatedBy: string;
+    readonly capabilities: readonly GovernanceServiceCapability[];
+    readonly occurredAt: string;
+    readonly expiresAt: string;
+    readonly reason: string;
+};
+export interface GovernanceCapabilityGrantRegistryOptions {
+    readonly now?: (() => number) | undefined;
+    readonly maxTtlMs?: number | undefined;
+    readonly maxGrants?: number | undefined;
+    readonly tokenMaterial?: (() => {
+        readonly grantId: string;
+        readonly secret: string;
+    }) | undefined;
+    readonly auditSink?: ((event: GovernanceGrantAuditEvent) => void) | undefined;
+}
+export declare class GovernanceCapabilityGrantRegistry {
+    readonly projectId: string;
+    private readonly records;
+    private readonly now;
+    private readonly maxTtlMs;
+    private readonly maxGrants;
+    private readonly tokenMaterial;
+    private readonly auditSink;
+    private auditSequence;
+    constructor(projectId: string, options?: GovernanceCapabilityGrantRegistryOptions);
+    issue(options: IssueGovernanceCapabilityGrantOptions): IssuedGovernanceCapabilityGrant;
+    rotate(grantId: string, options: RotateGovernanceCapabilityGrantOptions): IssuedGovernanceCapabilityGrant;
+    authenticate(credential: GovernanceServiceCredential): GovernanceCapabilityAuthenticationResult;
+    revoke(grantId: string, reason?: string, revokedBy?: string): boolean;
+    sweepExpired(reason?: string): number;
+    getGrant(grantId: string): GovernanceCapabilityGrant | null;
+    remainingTtlMs(grantId: string): number | null;
+    listGrants(): readonly GovernanceCapabilityGrant[];
+    private parseToken;
+    private describe;
+    private reject;
+    private appendAudit;
+    private pruneInactive;
+}
+//# sourceMappingURL=capability-grant.d.ts.map

package/dist/credential-lease-controller.d.ts

@@ -0,0 +1,85 @@
+import type { GovernanceServiceCredential } from './capability-grant.js';
+import type { GovernanceServiceResponse } from './project-service.js';
+export declare const GOVERNANCE_CREDENTIAL_LEASE_DEFAULT_TTL_MS: number;
+export declare const GOVERNANCE_CREDENTIAL_LEASE_DEFAULT_RENEW_BEFORE_MS: number;
+export declare const GOVERNANCE_CREDENTIAL_LEASE_DEFAULT_RETRY_MS = 1000;
+export declare const GOVERNANCE_CREDENTIAL_LEASE_DEFAULT_MAX_ATTEMPTS = 3;
+export type GovernanceCredentialLeaseState = 'idle' | 'scheduled' | 'rotating' | 'retry_wait' | 'stopped' | 'expired';
+export type GovernanceCredentialLeaseStopReason = 'stopped_by_owner' | 'retry_exhausted' | 'credential_expired';
+export interface GovernanceCredentialLeaseSnapshot {
+    readonly state: GovernanceCredentialLeaseState;
+    readonly projectId: string;
+    readonly clientId: string;
+    readonly grantId: string;
+    readonly expiresAt: string;
+    readonly rotationAttempt: number;
+    readonly nextActionAt?: string | undefined;
+    readonly stopReason?: GovernanceCredentialLeaseStopReason | undefined;
+    readonly lastFailure?: string | undefined;
+}
+export interface GovernanceCredentialLeaseScheduler {
+    schedule(callback: () => void, delayMs: number): unknown;
+    cancel(handle: unknown): void;
+}
+export interface GovernanceCredentialLeaseClient {
+    request(input: unknown): Promise<GovernanceServiceResponse>;
+}
+export interface GovernanceCredentialLeaseControllerOptions {
+    readonly projectRoot: string;
+    readonly projectId: string;
+    readonly grantId: string;
+    readonly expiresAt: string;
+    readonly credential: GovernanceServiceCredential;
+    readonly rotationTtlMs?: number | undefined;
+    readonly renewBeforeMs?: number | undefined;
+    readonly retryDelayMs?: number | undefined;
+    readonly maxAttempts?: number | undefined;
+    readonly requestTimeoutMs?: number | undefined;
+    readonly now?: (() => number) | undefined;
+    readonly scheduler?: GovernanceCredentialLeaseScheduler | undefined;
+    readonly requestIdFactory?: (() => string) | undefined;
+    readonly clientFactory?: ((credential: GovernanceServiceCredential) => GovernanceCredentialLeaseClient) | undefined;
+}
+/**
+ * Opt-in process-local holder for one self-rotating capability_admin credential.
+ * It never persists or exposes the current bearer token.
+ */
+export declare class GovernanceCredentialLeaseController implements GovernanceCredentialLeaseClient {
+    private readonly projectRoot;
+    private readonly projectId;
+    private readonly clientId;
+    private readonly rotationTtlMs;
+    private readonly renewBeforeMs;
+    private readonly retryDelayMs;
+    private readonly maxAttempts;
+    private readonly now;
+    private readonly scheduler;
+    private readonly requestIdFactory;
+    private readonly clientFactory;
+    private client;
+    private credential;
+    private grantId;
+    private expiresAtMs;
+    private state;
+    private rotationAttempt;
+    private cycleRequestId;
+    private timer;
+    private nextActionAtMs;
+    private stopReason;
+    private lastFailure;
+    private stopped;
+    private inFlight;
+    constructor(options: GovernanceCredentialLeaseControllerOptions);
+    start(): GovernanceCredentialLeaseSnapshot;
+    stop(): GovernanceCredentialLeaseSnapshot;
+    request(input: unknown): Promise<GovernanceServiceResponse>;
+    rotateNow(): Promise<GovernanceCredentialLeaseSnapshot>;
+    snapshot(): GovernanceCredentialLeaseSnapshot;
+    private rotateOnce;
+    private handleFailure;
+    private scheduleRenewal;
+    private schedule;
+    private clearTimer;
+    private expire;
+}
+//# sourceMappingURL=credential-lease-controller.d.ts.map

package/dist/daemon-control.d.ts

@@ -0,0 +1,48 @@
+import type { GovernanceAttachmentBrokerControllerSnapshot } from './attachment-broker-controller.js';
+export interface GovernanceDaemonControlStatus {
+    readonly projectId: string;
+    readonly pid: number;
+    readonly instanceId: string;
+    readonly startedAt: string;
+    readonly attachmentBroker?: GovernanceAttachmentBrokerControllerSnapshot | undefined;
+}
+export type GovernanceDaemonOperatorSignalLevel = 'healthy' | 'notice' | 'warning';
+export interface GovernanceDaemonOperatorAttachmentBrokerStatus {
+    readonly state: GovernanceAttachmentBrokerControllerSnapshot['state'];
+    readonly health: GovernanceAttachmentBrokerControllerSnapshot['health'];
+    readonly expiresAt?: string | undefined;
+    readonly nextActionAt?: string | undefined;
+    readonly consecutiveFailures: number;
+    readonly pendingRevocations: number;
+    readonly auditHealthy: boolean;
+}
+export interface GovernanceDaemonOperatorStatus {
+    readonly schemaVersion: 1;
+    readonly projectId: string;
+    readonly pid: number;
+    readonly instanceId: string;
+    readonly startedAt: string;
+    readonly signal: {
+        readonly level: GovernanceDaemonOperatorSignalLevel;
+        readonly code: 'attachment_broker_healthy' | 'attachment_broker_initializing' | 'attachment_broker_status_unavailable' | 'attachment_broker_degraded' | 'attachment_broker_audit_unhealthy' | 'attachment_broker_revocation_pending' | 'attachment_broker_stopped';
+        readonly message: string;
+        readonly operatorAction: 'none' | 'observe' | 'investigate';
+        readonly executionDisposition: 'continue';
+    };
+    readonly attachmentBroker: GovernanceDaemonOperatorAttachmentBrokerStatus | null;
+}
+/**
+ * Deterministic, credential-free operator projection. A warning is advisory:
+ * task and model execution continue until a separate policy gate says otherwise.
+ */
+export declare function projectGovernanceDaemonOperatorStatus(status: GovernanceDaemonControlStatus): GovernanceDaemonOperatorStatus;
+export interface GovernanceDaemonControlPort {
+    status(): GovernanceDaemonControlStatus;
+}
+export interface GovernanceDaemonShutdownNotice {
+    readonly requestId: string;
+    readonly expectedInstanceId: string;
+    readonly requestedBy: string;
+    readonly reason: string;
+}
+//# sourceMappingURL=daemon-control.d.ts.map