nawabari 0.1.0 → 0.2.0

package/dist/session-registry.d.ts

@@ -1,10 +1,16 @@
-import { type GitCommandRunner, type RepositoryContext } from "./git.js";
+import { type GitCommandRunner, type GitWorktreeInfo, type PhysicalExecutionContext, type RepositoryContext } from "./git.js";
 import { type RegistryErrorCode, type RegistryErrorDetails } from "./errors.js";
+import { RESOURCE_CLAIM_SCHEMA_VERSION, type ResourceClaim, type ResourceClaimInput, type ResourceClaimMode } from "./resource-claims.js";
+import { type CheckpointEvidence, type CheckpointOptions, type OperationAuthorizationDecision, type OperationAuthorizationOptions } from "./operation-authorization.js";
+export type { ResourceClaim } from "./resource-claims.js";
 export declare const REGISTRY_SCHEMA_VERSION: 1;
+export { RESOURCE_CLAIM_SCHEMA_VERSION };
 export declare const REGISTRY_DIRECTORY_NAME = "nawabari";
 export declare const REGISTRY_FILE_NAME = "session-registry.json";
 export declare const REGISTRY_LOCK_FILE_NAME = "session-registry.lock";
 export declare const DEFAULT_STALE_AFTER_MS: number;
+export declare const CLEANUP_DECISION_SCHEMA_VERSION: 1;
+export declare const RECONCILIATION_SCHEMA_VERSION: 1;
 export type RegistrySchemaVersion = typeof REGISTRY_SCHEMA_VERSION;
 export type SessionState = "new" | "active" | "closing" | "closed" | "stale";
 export interface SessionRecord {
@@ -53,6 +59,7 @@ export interface GarbageCollectBlocked {
     readonly code: RegistryErrorCode;
     readonly message: string;
     readonly details: RegistryErrorDetails;
+    readonly recoveryHints: readonly string[];
 }
 export interface GarbageCollectResult {
     readonly apply: boolean;
@@ -60,6 +67,83 @@ export interface GarbageCollectResult {
     readonly cleaned: readonly SessionRecord[];
     readonly blocked: readonly GarbageCollectBlocked[];
 }
+export interface CleanupBlocker {
+    readonly code: RegistryErrorCode;
+    readonly message: string;
+    readonly details: RegistryErrorDetails;
+    readonly recoveryHints: readonly string[];
+}
+export interface CleanupDecision {
+    readonly schemaVersion: typeof CLEANUP_DECISION_SCHEMA_VERSION;
+    readonly operation: "cleanup";
+    readonly allowed: boolean;
+    readonly code: "ALLOWED" | RegistryErrorCode;
+    readonly repositoryId: string;
+    readonly worktreePath: string;
+    readonly branchName: string;
+    readonly session: SessionRecord;
+    readonly claims: readonly ResourceClaim[];
+    readonly physicalState: string;
+    readonly blockers: readonly CleanupBlocker[];
+    readonly recoveryHints: readonly string[];
+}
+export type ReconciliationSessionStatus = "healthy" | "candidate" | "drift" | "closed";
+export interface ReconciliationSession {
+    readonly session: SessionRecord;
+    readonly status: ReconciliationSessionStatus;
+    readonly physicalState: string;
+    readonly blockers: readonly CleanupBlocker[];
+}
+export interface ReconciliationIssue {
+    readonly code: RegistryErrorCode;
+    readonly message: string;
+    readonly sessionId: string | null;
+    readonly worktreePath: string | null;
+    readonly branchName: string | null;
+    readonly details: RegistryErrorDetails;
+    readonly recoveryHints: readonly string[];
+}
+export interface ReconciliationResult {
+    readonly schemaVersion: typeof RECONCILIATION_SCHEMA_VERSION;
+    readonly repositoryId: string;
+    readonly worktrees: readonly GitWorktreeInfo[];
+    readonly sessions: readonly ReconciliationSession[];
+    readonly issues: readonly ReconciliationIssue[];
+    readonly clean: boolean;
+}
+export interface ClaimResourcesOptions {
+    readonly sessionId?: string | null;
+    readonly session_id?: string | null;
+    readonly claims: readonly ResourceClaimInput[];
+    readonly repositoryId?: string;
+    readonly repository_id?: string;
+}
+export interface UpdateClaimsOptions extends ClaimResourcesOptions {
+}
+export interface ReleaseClaimsOptions {
+    readonly sessionId?: string | null;
+    readonly session_id?: string | null;
+    readonly claimIds?: readonly string[];
+    readonly claim_ids?: readonly string[];
+}
+export interface ClaimResourcesResult {
+    readonly session: SessionRecord;
+    readonly claims: readonly ResourceClaim[];
+    readonly added: readonly ResourceClaim[];
+    readonly released: readonly ResourceClaim[];
+    readonly idempotent: boolean;
+}
+export interface ReleaseClaimsResult {
+    readonly sessionId: string;
+    readonly released: readonly ResourceClaim[];
+    readonly remaining: readonly ResourceClaim[];
+    readonly idempotent: boolean;
+}
+export interface RegistryMigrationResult {
+    readonly migrated: boolean;
+    readonly registrySchemaVersion: typeof REGISTRY_SCHEMA_VERSION;
+    readonly claimSchemaVersion: typeof RESOURCE_CLAIM_SCHEMA_VERSION;
+}
 export interface GuardOptions {
     readonly sessionId?: string | null;
 }
@@ -76,6 +160,50 @@ export interface GuardDecision {
     readonly state: SessionState | null;
     readonly details: RegistryErrorDetails;
 }
+export type { CheckpointEvidence, CheckpointOptions, OperationAuthorizationDecision, OperationAuthorizationOptions, } from "./operation-authorization.js";
+export { CHECKPOINT_EVIDENCE_SCHEMA_VERSION, CHECKPOINT_MAX_PATHS, OPERATION_AUTHORIZATION_SCHEMA_VERSION, OPERATION_REQUIRED_ACCESS, OPERATION_VOCABULARY, } from "./operation-authorization.js";
+export interface VerifiedExecutionContext extends PhysicalExecutionContext {
+    readonly session: SessionRecord;
+}
+export declare const GOVERNED_GIT_OPERATION_SCHEMA_VERSION: 1;
+export interface CommitOptions {
+    readonly sessionId?: string | null;
+    readonly session_id?: string | null;
+    readonly message: string;
+    /** Concrete repository-relative paths. Globs are never accepted here. */
+    readonly resources?: readonly string[];
+    /** Alias for callers that name the same explicit paths as paths. */
+    readonly paths?: readonly string[];
+}
+export interface CommitResult {
+    readonly schemaVersion: typeof GOVERNED_GIT_OPERATION_SCHEMA_VERSION;
+    readonly commitSha: string;
+    readonly message: string;
+    readonly resources: readonly string[];
+}
+export type PushRelation = "no-upstream" | "up-to-date" | "ahead" | "behind" | "diverged";
+export interface PushOptions {
+    readonly sessionId?: string | null;
+    readonly session_id?: string | null;
+    /** Explicit claim-covered resources; push never infers these from the registry. */
+    readonly resources?: readonly string[];
+    readonly remote?: string | null;
+    readonly branch?: string | null;
+    readonly remoteBranch?: string | null;
+    readonly remote_branch?: string | null;
+    readonly force?: boolean;
+    readonly createUpstream?: boolean;
+    readonly create_upstream?: boolean;
+}
+export interface PushResult {
+    readonly schemaVersion: typeof GOVERNED_GIT_OPERATION_SCHEMA_VERSION;
+    readonly remote: string;
+    readonly branch: string;
+    readonly target: string;
+    readonly relation: PushRelation;
+    readonly force: boolean;
+    readonly upstreamCreated: boolean;
+}
 export interface SessionRegistryOptions {
     readonly cwd?: string;
     readonly repository?: RepositoryContext;
@@ -109,10 +237,25 @@ export interface PersistedSessionRecord {
     readonly updated_at: string;
     readonly label?: string;
 }
+export interface PersistedResourceClaim {
+    readonly schema_version: typeof RESOURCE_CLAIM_SCHEMA_VERSION;
+    readonly claim_id: string;
+    readonly session_id: string;
+    readonly repository_id: string;
+    readonly worktree_path: string;
+    readonly resource: string;
+    readonly mode: ResourceClaimMode;
+    readonly created_at: string;
+    readonly updated_at: string;
+}
 export interface PersistedRegistry {
     readonly schema_version: RegistrySchemaVersion;
     readonly repository_id: string;
     readonly sessions: readonly PersistedSessionRecord[];
+    /** Optional in the TypeScript shape so v0.1.0 fixtures remain readable. */
+    readonly claims_schema_version?: typeof RESOURCE_CLAIM_SCHEMA_VERSION;
+    /** Optional in the TypeScript shape so v0.1.0 fixtures remain readable. */
+    readonly claims?: readonly PersistedResourceClaim[];
 }
 export declare class SessionRegistry {
     readonly repository: RepositoryContext;
@@ -133,6 +276,22 @@ export declare class SessionRegistry {
     read(): readonly SessionRecord[];
     list(): readonly SessionRecord[];
     get(sessionId: string): SessionRecord | undefined;
+    /** Return the single authoritative claim set, optionally scoped to a session. */
+    listClaims(sessionId?: string | null): readonly ResourceClaim[];
+    claims(sessionId?: string | null): readonly ResourceClaim[];
+    getClaim(claimId: string): ResourceClaim | undefined;
+    /**
+     * Explicitly materialize the v0.1.0 registry's empty claim section. This is
+     * also performed by the first ownership mutation after a legacy read.
+     */
+    migrate(): RegistryMigrationResult;
+    claim(sessionIdOrOptions: string | ClaimResourcesOptions, inputs?: readonly ResourceClaimInput[]): ClaimResourcesResult;
+    acquireClaims(sessionIdOrOptions: string | ClaimResourcesOptions, inputs?: readonly ResourceClaimInput[]): ClaimResourcesResult;
+    /** Add claims atomically. Repeating an equivalent operation is idempotent. */
+    claimResources(options: ClaimResourcesOptions): ClaimResourcesResult;
+    updateClaims(options: UpdateClaimsOptions): ClaimResourcesResult;
+    releaseClaims(sessionIdOrOptions: string | ReleaseClaimsOptions, claimIds?: readonly string[]): ReleaseClaimsResult;
+    releaseSessionClaims(sessionId: string): ReleaseClaimsResult;
     create(options?: CreateSessionOptions): SessionRecord;
     createSession(options?: CreateSessionOptions): SessionRecord;
     /** Provision one isolated Git worktree and commit its ownership atomically. */
@@ -143,27 +302,82 @@ export declare class SessionRegistry {
     registerSession(record: SessionRecord): SessionRecord;
     resolveCurrentSession(): SessionRecord;
     currentSession(): SessionRecord;
+    /**
+     * Resolve Git's physical facts and the registry's active owner as one
+     * fail-closed observation for governed operations.
+     */
+    verifyExecutionContext(options?: GuardOptions): VerifiedExecutionContext;
+    /** Shared physical/protected/ownership path for every governed decision. */
+    private verifyGovernedExecutionContext;
+    private resolveSessionOwnership;
     /**
      * Evaluate the current worktree as a Nawabari mutation context without taking
      * the registry lock or changing Git or registry state.
      */
     guard(options?: GuardOptions): GuardDecision;
+    /**
+     * The single claim-aware authorization decision for every governed local
+     * operation. Ownership is observed first; caller labels never substitute for
+     * the physical repository/worktree/branch facts or persisted claims.
+     */
+    authorizeOperation(options: OperationAuthorizationOptions): OperationAuthorizationDecision;
+    /**
+     * Stage and commit only caller-declared, claim-authorized resources.
+     * Authorization, physical observations, and Git mutation are serialized by
+     * the existing repository lock; this method does not introduce another
+     * ownership or mutation authority.
+     */
+    commit(options: CommitOptions): CommitResult;
+    commitSession(options: CommitOptions): CommitResult;
+    /** Push the currently owned branch to an explicit remote/branch target. */
+    push(options: PushOptions): PushResult;
+    pushSession(options: PushOptions): PushResult;
+    private requireMutationAuthorization;
+    /** Capture bounded Git evidence for the current owned session's declaration. */
+    checkpoint(options?: CheckpointOptions): CheckpointEvidence;
+    captureCheckpoint(options?: CheckpointOptions): CheckpointEvidence;
+    /**
+     * Produce the authoritative, non-mutating cleanup decision for one session.
+     * The decision observes registry claims and current Git/filesystem state in
+     * one repository-locked read; it never repairs drift or removes resources.
+     */
+    cleanupDecision(sessionIdOrOptions?: string | null | CloseSessionOptions): CleanupDecision;
+    /** Compatibility alias for callers that name the same authority an assessment. */
+    assessCleanup(sessionIdOrOptions?: string | null | CloseSessionOptions): CleanupDecision;
+    /**
+     * Reconcile registry ownership with Git's physical worktree inventory.
+     * This is deliberately diagnostic-only: no stale metadata is repaired and
+     * no physical resource is removed by this method.
+     */
+    reconcile(): ReconciliationResult;
+    reconcileState(): ReconciliationResult;
     /** Close one session only after its ownership and recoverability are proven safe. */
     close(sessionIdOrOptions?: string | null | CloseSessionOptions): CloseSessionResult;
     closeSession(sessionIdOrOptions?: string | null | CloseSessionOptions): CloseSessionResult;
     /** Detect stale sessions, optionally applying only cleanup that passes close preflight. */
     garbageCollect(options?: GarbageCollectOptions): GarbageCollectResult;
     gc(options?: GarbageCollectOptions): GarbageCollectResult;
+    private resolveOwnerSession;
+    private selectSessionId;
+    private claimOwner;
+    private canonicalClaimInputs;
+    private addClaimsUnsafe;
+    private validateRequestedClaims;
     private closeUnsafe;
     private inspectCleanupResources;
+    private cleanupDecisionUnsafe;
+    private assertCleanupAllowed;
+    private reconcileSessionUnsafe;
     private protectedWorktree;
     private protectedBranch;
     private branchIsReachableFromIntegration;
     private resolveProvisioningResources;
     private resolveCreationResources;
+    private readStateUnsafe;
     private readUnsafe;
     private writeUnsafe;
     private mutate;
     private withLock;
 }
 export declare function toPersistedSessionRecord(record: SessionRecord, expectedRepositoryId?: string): PersistedSessionRecord;
+export declare function toPersistedResourceClaim(claim: ResourceClaim, expectedRepositoryId?: string): PersistedResourceClaim;