agent-plugkit 0.1.0

package/dist/infrastructure/document-commit.d.ts

@@ -0,0 +1,165 @@
+/**
+ * These names are reserved transaction traces inside an authorized workspace.
+ * They are not product state. A valid lock records the only staging token that
+ * may be reclaimed after its owner has exited.
+ */
+export declare const WORKSPACE_WRITE_LOCK = ".agent-plugkit-write.lock";
+export declare const DOCUMENT_STAGING_PREFIX = ".agent-plugkit-document-";
+export interface AtomicDocumentCommitRequest {
+    readonly directory: string;
+    readonly relativePath: string;
+    readonly expectedRevision: string;
+    readonly nextBytes: Uint8Array;
+}
+export interface AtomicDocumentCreateFile {
+    readonly relativePath: string;
+    readonly bytes: Uint8Array;
+    readonly mode: number;
+}
+/**
+ * A component declaration can require a new canonical scaffold (currently a
+ * Skill document or Hook script). The document and those exclusive-create
+ * files share the same workspace lock and staging root. Existing user files
+ * are never replaced by this operation.
+ */
+export interface AtomicDocumentAndFilesCommitRequest extends AtomicDocumentCommitRequest {
+    readonly createFiles: readonly AtomicDocumentCreateFile[];
+}
+export interface AtomicDocumentAndFilesCommitDependencies extends AtomicDocumentCommitDependencies {
+    readonly beforeCreateFile?: (stagedPath: string, targetPath: string) => void;
+    readonly createFile?: (stagedPath: string, targetPath: string) => void;
+    readonly rollbackFile?: (targetPath: string) => void;
+    readonly rollbackDocument?: (backupPath: string, targetPath: string) => void;
+}
+export interface AtomicDocumentAndFilesTransactionFacts {
+    readonly canonical: "unchanged" | "committed" | "restored" | "uncertain";
+    readonly scaffolds: "none" | "committed" | "rolled-back" | "residual";
+    readonly cleanupComplete: boolean;
+}
+export type AtomicDocumentAndFilesCommitResult = AtomicDocumentCommitResult & {
+    readonly transaction: AtomicDocumentAndFilesTransactionFacts;
+};
+/**
+ * `diskChanged` reports a canonical document replacement or transaction
+ * residue left by this call. Successfully reclaimed prior transaction traces
+ * and transient no-clobber links do not turn it on.
+ */
+export type AtomicDocumentCommitResult = {
+    readonly status: 'committed';
+    readonly revision: string;
+    readonly diskChanged: true;
+    readonly changedPaths: readonly string[];
+    readonly cleanupComplete: true;
+} | {
+    readonly status: 'verified';
+    readonly revision: string;
+    readonly diskChanged: false;
+    readonly changedPaths: readonly [];
+    readonly cleanupComplete: true;
+} | {
+    readonly status: 'conflict';
+    readonly currentRevision: string;
+    readonly diskChanged: false;
+    readonly changedPaths: readonly [];
+    readonly cleanupComplete: true;
+} | {
+    readonly status: 'busy';
+    readonly message: string;
+    readonly diskChanged: false;
+    readonly changedPaths: readonly [];
+    readonly cleanupComplete: true;
+} | {
+    readonly status: 'failed';
+    readonly message: string;
+    readonly diskChanged: boolean;
+    readonly changedPaths: readonly string[];
+    readonly cleanupComplete: boolean;
+};
+export interface AtomicDocumentCommitDependencies {
+    readonly createToken?: () => string;
+    readonly now?: () => Date;
+    readonly isProcessAlive?: (processId: number) => boolean;
+    readonly afterReclaimLink?: (lockPath: string, quarantinePath: string) => void;
+    readonly beforeLockSync?: (lockPath: string) => void;
+    readonly afterLock?: () => void;
+    readonly beforeStageWrite?: (stagedPath: string) => void;
+    readonly syncStagedFile?: (stagedPath: string) => void;
+    readonly afterStageWrite?: (stagedPath: string) => void;
+    readonly beforeRevisionRecheck?: (targetPath: string) => void;
+    readonly replaceDocument?: (stagedPath: string, targetPath: string) => void;
+    readonly syncParentDirectory?: (directory: string) => void;
+    readonly afterReplace?: (targetPath: string) => void;
+    readonly cleanupStaging?: (stagingRoot: string) => void;
+    readonly cleanupLock?: (lockPath: string, token: string) => void;
+}
+export type AtomicArtifactMutation = {
+    readonly relativePath: string;
+    readonly action: "write";
+    readonly bytes: Uint8Array;
+    readonly mode?: number;
+} | {
+    readonly relativePath: string;
+    readonly action: "delete";
+};
+export interface AtomicArtifactExpectation {
+    readonly relativePath: string;
+    readonly revision: string | "missing";
+}
+export interface AtomicArtifactGroupCommitRequest {
+    readonly directory: string;
+    readonly expectations: readonly AtomicArtifactExpectation[];
+    readonly mutations: readonly AtomicArtifactMutation[];
+}
+export interface AtomicArtifactGroupCommitDependencies extends Pick<AtomicDocumentCommitDependencies, "createToken" | "now" | "isProcessAlive" | "beforeLockSync" | "afterReclaimLink"> {
+    readonly beforeMutation?: (relativePath: string) => void;
+    readonly replaceArtifact?: (stagedPath: string, targetPath: string) => void;
+    readonly beforeRollback?: (relativePath: string) => void;
+    readonly removeCreatedDirectory?: (path: string, relativePath: string) => void;
+    readonly cleanupStaging?: (stagingRoot: string) => void;
+    readonly cleanupLock?: (lockPath: string, token: string) => void;
+}
+export type AtomicArtifactGroupCommitResult = {
+    readonly status: "committed" | "verified";
+    readonly changedPaths: readonly string[];
+    readonly diskChanged: boolean;
+    readonly rolledBack: false;
+    readonly cleanupComplete: true;
+} | {
+    readonly status: "conflict" | "busy";
+    readonly message: string;
+    readonly changedPaths: readonly [];
+    readonly diskChanged: false;
+    readonly rolledBack: false;
+    readonly cleanupComplete: true;
+} | {
+    readonly status: "failed";
+    readonly message: string;
+    readonly changedPaths: readonly string[];
+    readonly diskChanged: boolean;
+    readonly rolledBack: boolean;
+    readonly cleanupComplete: boolean;
+};
+export declare function documentRevision(bytes: Uint8Array): string;
+/**
+ * Commits one already-authorized document with a workspace-wide exclusive
+ * lock. Domain ownership and patching stay with the caller. Atomicity means
+ * readers see either the old or new target after rename; durability is only
+ * reported as committed after both the staged file and its parent directory
+ * have been fsynced.
+ */
+export declare function commitAuthorizedDocument(request: AtomicDocumentCommitRequest, dependencies?: AtomicDocumentCommitDependencies): AtomicDocumentCommitResult;
+/**
+ * Commits a canonical document plus exclusive-create scaffold files under one
+ * existing workspace-wide lock. It deliberately does not support update or
+ * deletion of auxiliary files: those objects remain user-owned unless a
+ * separate, explicit object-level Trash action is confirmed.
+ */
+export declare function commitAuthorizedDocumentAndFiles(request: AtomicDocumentAndFilesCommitRequest, dependencies?: AtomicDocumentAndFilesCommitDependencies): AtomicDocumentAndFilesCommitResult;
+/**
+ * Commits one generated-artifact consistency group under the same
+ * workspace-wide lock used by canonical document writes. All bytes and
+ * deletions are staged before the first canonical mutation. A failure rolls
+ * already-applied members back from private backups; callers must treat any
+ * cleanup uncertainty as failure rather than declaring the group successful.
+ */
+export declare function commitAuthorizedArtifactGroup(request: AtomicArtifactGroupCommitRequest, dependencies?: AtomicArtifactGroupCommitDependencies): AtomicArtifactGroupCommitResult;