@agent-teams/repository-mutation 0.0.0

package/dist/transaction-coordination/mutation-lease.js

@@ -0,0 +1,351 @@
+import { lstat, opendir, realpath } from "node:fs/promises";
+import { resolve, join } from "node:path";
+import { sha256Json } from "../canonical-json.js";
+import { RepositoryMutationError } from "../errors.js";
+import { KNOWN_FILE_TRANSACTION_TEMPORARY_FILE, LOCAL_STATE_DIRECTORY, FOUNDATION_TRANSACTION_FILE, TRANSACTION_TEMPORARY_FILE } from "../state-contract.js";
+import { NodeMutationOperationLock } from "./adapters/node/node-operation-lock.js";
+const leases = new WeakMap();
+const observations = new WeakMap();
+const claims = new WeakMap();
+const commonEvidenceNames = Object.freeze([
+    FOUNDATION_TRANSACTION_FILE,
+    TRANSACTION_TEMPORARY_FILE,
+    KNOWN_FILE_TRANSACTION_TEMPORARY_FILE
+]);
+const maximumStateDirectoryEntries = 1024;
+function portableStateName(name) {
+    return name.normalize("NFC").toLowerCase();
+}
+function isSuspiciousCommonEvidenceName(name) {
+    const portable = portableStateName(name);
+    const transaction = portableStateName(FOUNDATION_TRANSACTION_FILE);
+    const terminalKnownFileEvidenceName = `${FOUNDATION_TRANSACTION_FILE}.completed-known-file-evidence`;
+    const terminalKnownFileEvidence = portableStateName(terminalKnownFileEvidenceName);
+    const terminalEvidence = new RegExp(`^${transaction.replaceAll(".", "\\.")}\\.completed-[a-z0-9-]+-evidence$`, "u");
+    return commonEvidenceNames.some((expected) => portable === portableStateName(expected) && name !== expected) ||
+        (portable.startsWith(`${transaction}.`) &&
+            (portable !== terminalKnownFileEvidence || name !== terminalKnownFileEvidenceName) &&
+            (!terminalEvidence.test(portable) || name !== portable) &&
+            !commonEvidenceNames.includes(name)) ||
+        portable.includes("cleanup-residue");
+}
+async function boundedSuspiciousStateNames(directory) {
+    const handle = await opendir(directory);
+    const suspicious = [];
+    let entries = 0;
+    try {
+        for (;;) {
+            const entry = await handle.read();
+            if (entry === null) {
+                return suspicious.toSorted();
+            }
+            entries += 1;
+            if (entries > maximumStateDirectoryEntries) {
+                invalid("MUTATION_CLAIM_INVALID", "Mutation state contains too many entries to classify common evidence safely.");
+            }
+            if (isSuspiciousCommonEvidenceName(entry.name)) {
+                suspicious.push(entry.name);
+            }
+        }
+    }
+    finally {
+        await handle.close();
+    }
+}
+function invalid(code, message) {
+    throw new RepositoryMutationError(code, message);
+}
+function leaseState(lease) {
+    const state = leases.get(lease);
+    if (state === undefined || state.released) {
+        invalid("MUTATION_LEASE_INVALID", "Mutation lease is forged, released, or unavailable.");
+    }
+    return state;
+}
+function isMissing(error) {
+    return error instanceof Error && "code" in error &&
+        error.code === "ENOENT";
+}
+async function physicalRootIdentity(root) {
+    const metadata = await lstat(root, { bigint: true });
+    if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
+        invalid("MUTATION_LEASE_INVALID", "Mutation repository root is not one physical directory.");
+    }
+    return {
+        birthtimeNs: metadata.birthtimeNs,
+        dev: metadata.dev,
+        ino: metadata.ino
+    };
+}
+async function assertPhysicalRoot(state) {
+    let current;
+    try {
+        current = await physicalRootIdentity(state.root);
+    }
+    catch (error) {
+        if (error instanceof RepositoryMutationError) {
+            throw error;
+        }
+        invalid("MUTATION_LEASE_INVALID", "Mutation repository root cannot be revalidated.");
+    }
+    if (current.birthtimeNs !== state.rootIdentity.birthtimeNs ||
+        current.dev !== state.rootIdentity.dev || current.ino !== state.rootIdentity.ino) {
+        state.retained = true;
+        invalid("MUTATION_LEASE_INVALID", "Mutation repository root changed after the physical lease was acquired.");
+    }
+}
+async function boundedStateSnapshot(root) {
+    const directory = join(root, LOCAL_STATE_DIRECTORY);
+    let directoryEntry;
+    try {
+        directoryEntry = await lstat(directory, { bigint: true });
+    }
+    catch (error) {
+        if (isMissing(error)) {
+            return { fingerprint: "absent", commonEvidence: false };
+        }
+        throw error;
+    }
+    if (!directoryEntry.isDirectory() || directoryEntry.isSymbolicLink()) {
+        return { fingerprint: "invalid-state-directory", commonEvidence: true };
+    }
+    const suspiciousNames = await boundedSuspiciousStateNames(directory);
+    const observedNames = [...new Set([...commonEvidenceNames, ...suspiciousNames])].toSorted();
+    const records = [];
+    for (const name of observedNames) {
+        try {
+            const entry = await lstat(join(directory, name), { bigint: true });
+            records.push({
+                name,
+                kind: entry.isFile() ? "file" : entry.isDirectory() ? "directory" : "other",
+                dev: entry.dev.toString(),
+                ino: entry.ino.toString(),
+                size: entry.size.toString(),
+                mtimeNs: entry.mtimeNs.toString()
+            });
+        }
+        catch (error) {
+            if (!isMissing(error)) {
+                throw error;
+            }
+        }
+    }
+    return {
+        fingerprint: sha256Json({
+            domain: "agent-teams.repository-mutation.observation/v1",
+            directory: {
+                dev: directoryEntry.dev.toString(),
+                ino: directoryEntry.ino.toString(),
+                mtimeNs: directoryEntry.mtimeNs.toString()
+            },
+            records
+        }),
+        commonEvidence: records.length > 0
+    };
+}
+async function stateSnapshot(root) {
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        const first = await boundedStateSnapshot(root);
+        const second = await boundedStateSnapshot(root);
+        if (first.fingerprint === second.fingerprint &&
+            first.commonEvidence === second.commonEvidence) {
+            return second;
+        }
+    }
+    invalid("MUTATION_CLAIM_INVALID", "Mutation state changed during bounded observation.");
+}
+function inertRecord(value, keys, label) {
+    if (typeof value !== "object" || value === null || Array.isArray(value) ||
+        ![Object.prototype, null].includes(Object.getPrototypeOf(value))) {
+        invalid("MUTATION_CLAIM_INVALID", `${label} is not inert record data.`);
+    }
+    const ownKeys = Reflect.ownKeys(value);
+    if (ownKeys.some((key) => typeof key !== "string") ||
+        ownKeys.toSorted().join(",") !== keys.toSorted().join(",")) {
+        invalid("MUTATION_CLAIM_INVALID", `${label} has an invalid shape.`);
+    }
+    const record = {};
+    for (const key of keys) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (descriptor === undefined || !("value" in descriptor) || !descriptor.enumerable) {
+            invalid("MUTATION_CLAIM_INVALID", `${label} must contain only enumerable data properties.`);
+        }
+        record[key] = descriptor.value;
+    }
+    return record;
+}
+function snapshotArtifact(value, label) {
+    const candidate = inertRecord(value, ["buildIdentity", "name", "version"], `${label} artifact identity`);
+    if (typeof candidate["name"] !== "string" || candidate["name"].length === 0 ||
+        typeof candidate["version"] !== "string" || candidate["version"].length === 0 ||
+        typeof candidate["buildIdentity"] !== "string" ||
+        !/^sha256:[0-9a-f]{64}$/u.test(candidate["buildIdentity"])) {
+        invalid("MUTATION_CLAIM_INVALID", `${label} artifact identity is invalid.`);
+    }
+    return Object.freeze({
+        name: candidate["name"],
+        version: candidate["version"],
+        buildIdentity: candidate["buildIdentity"]
+    });
+}
+function snapshotIntent(intent) {
+    if (typeof intent !== "object" || intent === null || Array.isArray(intent) ||
+        ![Object.prototype, null].includes(Object.getPrototypeOf(intent))) {
+        invalid("MUTATION_CLAIM_INVALID", "Mutation intent is not inert record data.");
+    }
+    const kindDescriptor = Object.getOwnPropertyDescriptor(intent, "kind");
+    if (kindDescriptor === undefined || !("value" in kindDescriptor)) {
+        invalid("MUTATION_CLAIM_INVALID", "Mutation intent kind must be inert data.");
+    }
+    const candidate = inertRecord(intent, kindDescriptor.value === "apply-known-file"
+        ? ["kernelArtifact", "kind", "ownerArtifact", "planDigest"]
+        : ["kernelArtifact", "kind", "ownerArtifact"], "Mutation intent");
+    const ownerArtifact = snapshotArtifact(candidate["ownerArtifact"], "Owner");
+    const kernelArtifact = snapshotArtifact(candidate["kernelArtifact"], "Kernel");
+    if (candidate["kind"] === "apply-known-file" &&
+        typeof candidate["planDigest"] === "string" &&
+        /^sha256:[0-9a-f]{64}$/u.test(candidate["planDigest"])) {
+        return Object.freeze({
+            kind: "apply-known-file",
+            planDigest: candidate["planDigest"],
+            ownerArtifact,
+            kernelArtifact
+        });
+    }
+    if (candidate["kind"] === "recover-known-file") {
+        return Object.freeze({ kind: "recover-known-file", ownerArtifact, kernelArtifact });
+    }
+    invalid("MUTATION_CLAIM_INVALID", "Mutation intent is not one closed known-file intent.");
+}
+export async function acquireMutationLease(root) {
+    const canonicalRoot = await realpath(resolve(root));
+    const rootIdentity = await physicalRootIdentity(canonicalRoot);
+    const release = await new NodeMutationOperationLock(canonicalRoot).acquire();
+    const currentIdentity = await physicalRootIdentity(canonicalRoot);
+    if (currentIdentity.birthtimeNs !== rootIdentity.birthtimeNs ||
+        currentIdentity.dev !== rootIdentity.dev || currentIdentity.ino !== rootIdentity.ino) {
+        await release({ retainTransactionBarrier: true });
+        invalid("MUTATION_LEASE_INVALID", "Mutation repository root changed while its physical lease was acquired.");
+    }
+    const lease = Object.freeze({});
+    leases.set(lease, {
+        root: canonicalRoot,
+        rootIdentity,
+        release,
+        released: false,
+        retained: false,
+        sequence: 0
+    });
+    return lease;
+}
+export async function observeMutationState(lease) {
+    const state = leaseState(lease);
+    await assertPhysicalRoot(state);
+    const snapshot = await stateSnapshot(state.root);
+    const observation = Object.freeze({});
+    observations.set(observation, {
+        lease,
+        fingerprint: snapshot.fingerprint,
+        commonEvidence: snapshot.commonEvidence,
+        sequence: state.sequence
+    });
+    return observation;
+}
+export async function claimMutation(lease, observation, intent) {
+    const state = leaseState(lease);
+    await assertPhysicalRoot(state);
+    const observed = observations.get(observation);
+    if (observed === undefined || observed.lease !== lease || observed.sequence !== state.sequence) {
+        invalid("MUTATION_CLAIM_INVALID", "Mutation observation is forged, stale, or belongs to another lease.");
+    }
+    const current = await stateSnapshot(state.root);
+    if (observed.fingerprint !== current.fingerprint) {
+        invalid("MUTATION_CLAIM_INVALID", "Mutation observation became stale before the claim was issued.");
+    }
+    const capturedIntent = snapshotIntent(intent);
+    if (capturedIntent.kind === "apply-known-file" && observed.commonEvidence) {
+        invalid("MUTATION_CLAIM_INVALID", "Common transaction evidence must be recovered before apply.");
+    }
+    if (capturedIntent.kind === "recover-known-file" && !observed.commonEvidence) {
+        invalid("MUTATION_CLAIM_INVALID", "Known-file recovery requires common transaction evidence.");
+    }
+    const claim = Object.freeze({});
+    state.sequence += 1;
+    claims.set(claim, {
+        lease,
+        intent: capturedIntent,
+        fingerprint: observed.fingerprint,
+        commonEvidence: observed.commonEvidence,
+        sequence: state.sequence,
+        consumed: false
+    });
+    return claim;
+}
+export async function consumeMutationClaim(claim, expectedKind) {
+    const claimState = claims.get(claim);
+    if (claimState === undefined || claimState.consumed || claimState.intent.kind !== expectedKind) {
+        invalid("MUTATION_CLAIM_INVALID", "Mutation claim is forged, consumed, or has the wrong intent.");
+    }
+    const state = leaseState(claimState.lease);
+    await assertPhysicalRoot(state);
+    if (claimState.sequence !== state.sequence) {
+        invalid("MUTATION_CLAIM_INVALID", "Mutation claim generation became stale before consumption.");
+    }
+    const current = await stateSnapshot(state.root);
+    if (current.fingerprint !== claimState.fingerprint ||
+        current.commonEvidence !== claimState.commonEvidence) {
+        if (current.commonEvidence) {
+            state.retained = true;
+        }
+        invalid("MUTATION_CLAIM_INVALID", "Mutation claim evidence became stale before consumption.");
+    }
+    claimState.consumed = true;
+    state.sequence += 1;
+    return state.root;
+}
+export function mutationClaimIntent(claim) {
+    const claimState = claims.get(claim);
+    if (claimState === undefined || claimState.consumed) {
+        invalid("MUTATION_CLAIM_INVALID", "Mutation claim is forged or consumed.");
+    }
+    leaseState(claimState.lease);
+    return claimState.intent;
+}
+export async function retainMutationClaimBarrierOnEvidence(claim) {
+    const claimState = claims.get(claim);
+    if (claimState === undefined) {
+        return;
+    }
+    const state = leaseState(claimState.lease);
+    try {
+        if ((await stateSnapshot(state.root)).commonEvidence) {
+            state.retained = true;
+        }
+    }
+    catch {
+        state.retained = true;
+    }
+}
+export async function retainMutationBarrierOnEvidence(lease) {
+    const state = leaseState(lease);
+    try {
+        if (!(await stateSnapshot(state.root)).commonEvidence) {
+            return false;
+        }
+    }
+    catch {
+        state.retained = true;
+        return true;
+    }
+    state.retained = true;
+    return true;
+}
+export function retainMutationBarrier(lease) {
+    leaseState(lease).retained = true;
+}
+export async function releaseMutationLease(lease) {
+    const state = leaseState(lease);
+    await state.release({ retainTransactionBarrier: state.retained });
+    state.released = true;
+}
+//# sourceMappingURL=mutation-lease.js.map

package/dist/transaction-coordination/mutation-lease.js.map

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

package/package.json

@@ -0,0 +1,52 @@
+{
+  "description": "Closed, portable repository mutation and exact recovery primitives.",
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "typescript": "7.0.2"
+  },
+  "engines": {
+    "node": ">=24.18.0 <25",
+    "pnpm": ">=11.17.0 <12"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js"
+    },
+    "./qualification": {
+      "types": "./dist/qualification/index.d.ts",
+      "import": "./dist/qualification/index.js"
+    },
+    "./schemas/*": "./schemas/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "schemas",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "license": "Apache-2.0",
+  "name": "@agent-teams/repository-mutation",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agent-teams-ai/engineering-foundation.git",
+    "directory": "packages/repository-mutation"
+  },
+  "scripts": {
+    "build": "tsc --build tsconfig.json --pretty false"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "version": "0.0.0"
+}

package/schemas/known-file-transaction-plan/v1.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-teams.ai/schemas/known-file-transaction-plan/v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "protocol", "operations", "planDigest"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "protocol": { "const": "agent-teams.repository-mutation.known-file/v1" },
+    "operations": {
+      "type": "array",
+      "maxItems": 32,
+      "items": { "$ref": "#/$defs/operation" }
+    },
+    "planDigest": { "$ref": "#/$defs/sha256" }
+  },
+  "$defs": {
+    "sha256": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "image": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["contentBase64", "digest", "mode", "size"],
+      "properties": {
+        "contentBase64": { "type": "string", "contentEncoding": "base64" },
+        "digest": { "$ref": "#/$defs/sha256" },
+        "mode": { "type": "integer", "minimum": 0, "maximum": 511 },
+        "size": { "type": "integer", "minimum": 0, "maximum": 8388608 }
+      }
+    },
+    "precondition": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["state"],
+          "properties": { "state": { "const": "absent" } }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["state", "acceptedPreimages"],
+          "properties": {
+            "state": { "const": "known-file" },
+            "acceptedPreimages": {
+              "type": "array",
+              "minItems": 1,
+              "maxItems": 16,
+              "items": { "$ref": "#/$defs/image" }
+            }
+          }
+        }
+      ]
+    },
+    "operation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "precondition", "postimage"],
+      "properties": {
+        "path": { "type": "string", "minLength": 1, "maxLength": 1024 },
+        "precondition": { "$ref": "#/$defs/precondition" },
+        "postimage": { "$ref": "#/$defs/image" }
+      }
+    }
+  }
+}

package/schemas/known-file-transaction-receipt/v1.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-teams.ai/schemas/known-file-transaction-receipt/v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "protocol", "planDigest", "outcome", "operations", "receiptDigest"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "protocol": { "const": "agent-teams.repository-mutation.known-file/v1" },
+    "planDigest": { "$ref": "#/$defs/sha256" },
+    "outcome": { "enum": ["already-satisfied", "applied", "rolled-back"] },
+    "operations": {
+      "type": "array",
+      "maxItems": 32,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "outcome"],
+        "properties": {
+          "path": { "type": "string", "minLength": 1, "maxLength": 1024 },
+          "outcome": { "enum": ["already-satisfied", "created", "replaced", "rolled-back-to-absent", "rolled-back-to-preimage"] },
+          "resultDigest": { "$ref": "#/$defs/sha256" }
+        },
+        "allOf": [{
+          "if": { "properties": { "outcome": { "const": "rolled-back-to-absent" } }, "required": ["outcome"] },
+          "then": { "properties": { "resultDigest": false } },
+          "else": { "required": ["resultDigest"] }
+        }]
+      }
+    },
+    "receiptDigest": { "$ref": "#/$defs/sha256" }
+  },
+  "$defs": {
+    "sha256": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }
+  }
+}

package/schemas/repository-mutation-transaction-envelope/v1.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-teams.ai/schemas/repository-mutation-transaction-envelope/v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion", "format", "operationKind", "recoveryHandler",
+    "ownerArtifact", "kernelArtifact", "adapterContractVersion", "payloadKind",
+    "state", "payload", "payloadDigest", "envelopeDigest"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 6 },
+    "format": { "const": "agent-teams.repository-mutation.transaction-envelope/v1" },
+    "operationKind": { "type": "string", "minLength": 1, "maxLength": 256 },
+    "recoveryHandler": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "contractVersion"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1, "maxLength": 256 },
+        "contractVersion": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "ownerArtifact": { "$ref": "#/$defs/artifact" },
+    "kernelArtifact": { "$ref": "#/$defs/artifact" },
+    "adapterContractVersion": { "type": "integer", "minimum": 1 },
+    "payloadKind": { "type": "string", "minLength": 1, "maxLength": 256 },
+    "state": { "type": "string", "minLength": 1, "maxLength": 256 },
+    "payload": {},
+    "payloadDigest": { "$ref": "#/$defs/sha256" },
+    "envelopeDigest": { "$ref": "#/$defs/sha256" }
+  },
+  "$defs": {
+    "sha256": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "artifact": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "version", "buildIdentity"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1, "maxLength": 1024 },
+        "version": { "type": "string", "minLength": 1, "maxLength": 1024 },
+        "buildIdentity": { "$ref": "#/$defs/sha256" }
+      }
+    }
+  }
+}