taskflow-core 0.2.9 → 0.3.0-beta.1

package/dist/resources/file-transaction.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Resource-controlled file mutation transaction.
+ *
+ * This module is deliberately internal to `resources/execution.ts`: callers
+ * receive transactions only after host authority and PathRef resolution. It
+ * owns the data-plane sequence beneath that boundary:
+ *
+ *   durable snapshots -> atomic multi-scope lease -> durable intent/permit
+ *   -> stage -> promote -> commit-content | restore + abort-restored
+ *
+ * The local backend provides taskflow-exclusive isolation. It does not claim
+ * hostile external-process fencing; concurrent Taskflow writers are excluded
+ * by the persistent lease and unexpected external changes fail closed.
+ */
+import type { ResolvedPathRef } from "./resolve.ts";
+import type { WriteIntentJournal, PreparedMutation, WriteIntentRecord } from "./journal.ts";
+import type { LeaseHandle, PersistentLeaseCoordinator } from "./leases.ts";
+import type { ExecutionOwner, ScopedContentEvidence } from "./types.ts";
+export interface ResolvedFileWriteTarget {
+    effectId: string;
+    ref: ResolvedPathRef;
+}
+export interface FileWritePayload {
+    effectId: string;
+    content: string | Buffer;
+}
+export type FileTransactionResult = {
+    ok: true;
+    intentId: string;
+    committedPaths: string[];
+    commitGeneration: number;
+} | {
+    ok: false;
+    intentId: string;
+    code: "declared-path-bypass" | "commit-rejected";
+    reason: string;
+    restored: true;
+};
+interface SnapshotManifest {
+    version: 1;
+    artifactId: string;
+    effectId: string;
+    physicalPath: string;
+    logicalSubpath: string;
+    exists: boolean;
+    contentId: string;
+    mode?: number;
+    nearestExistingAncestor: string;
+    blobPath?: string;
+}
+interface Snapshot extends SnapshotManifest {
+    capabilityBindingId: string;
+    scopeDigest: string;
+}
+export interface ResourceFileTransactionOptions {
+    controlDirectory: string;
+    resourceDomainId: string;
+    owner: ExecutionOwner;
+    targets: readonly ResolvedFileWriteTarget[];
+    leases: PersistentLeaseCoordinator;
+    journal: WriteIntentJournal;
+    leaseTimeoutMs: number;
+    permitTtlMs: number;
+    signal?: AbortSignal;
+    authorizationPrincipalId?: string;
+    authorizationScopeRoot: string;
+    /** Preserve a failed authenticated release for the session's next-admission drain. */
+    onDeferredLeaseRelease?: (lease: LeaseHandle) => void;
+    /** Internal fault-injection seam for post-terminal staging cleanup tests. */
+    cleanupStaging?: (stagingDirectory: string) => void;
+}
+/** Remove terminal and pre-intent orphan before-images while retaining any
+ * pending/dirty transaction needed for recovery or explicit reconciliation. */
+export declare function garbageCollectResourceFileTransactions(controlDirectory: string, intents: readonly WriteIntentRecord[]): void;
+/** Restore a stale content intent while journal recovery holds its mutex. */
+export declare function recoverResourceFileIntent(options: {
+    controlDirectory: string;
+    intent: WriteIntentRecord;
+    leases: PersistentLeaseCoordinator;
+    leaseTimeoutMs: number;
+    signal?: AbortSignal;
+}): Promise<{
+    scopes: ScopedContentEvidence[];
+    reason: string;
+    restorableSnapshotArtifactIds: string[];
+} | undefined>;
+export declare class PreparedResourceFileTransaction {
+    #private;
+    readonly intentId: string;
+    constructor(input: {
+        snapshots: readonly Snapshot[];
+        mutation: PreparedMutation;
+        lease: LeaseHandle;
+        journal: WriteIntentJournal;
+        stagingDirectory: string;
+        onDeferredLeaseRelease?: (lease: LeaseHandle) => void;
+        authorizationScopeRoot: string;
+        cleanupStaging?: (stagingDirectory: string) => void;
+    });
+    commit(payloads: readonly FileWritePayload[]): Promise<FileTransactionResult>;
+    reject(reason: string): Promise<FileTransactionResult>;
+}
+export declare function prepareResourceFileTransaction(options: ResourceFileTransactionOptions): Promise<PreparedResourceFileTransaction>;
+export {};
+//# sourceMappingURL=file-transaction.d.ts.map

package/dist/resources/file-transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-transaction.d.ts","sourceRoot":"","sources":["../../src/resources/file-transaction.ts"],"names":[],"mappings":"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"}