tracegrove 0.0.0-stage → 0.3.0

package/dist/core/capabilityLifecycle.d.ts

@@ -0,0 +1,366 @@
+/** Pure lifecycle decisions. No retries, reset, filesystem access or cleanup is performed here. */
+import { type Ref } from '../protocol/index.ts';
+export declare function planCapabilityRetry(policyValue: unknown, stateValue: unknown): {
+    decision: "retry" | "stop" | "reconcile";
+    reason: string;
+    delayMs: number | null;
+    priorAttemptRef: {
+        id: string;
+        revision: string;
+        digest: {
+            algorithm: "sha256";
+            hex: string;
+        };
+    };
+    retainedArtifactRefs: {
+        id: string;
+        revision: string;
+        digest: {
+            algorithm: "sha256";
+            hex: string;
+        };
+    }[];
+};
+/** Resolve inventory against host-owned records. Ambiguity/staleness always needs reconciliation. */
+export declare function planCapabilityTeardown(checkpointValue: unknown, currentValue: unknown, ownedValues: unknown[], now?: number): {
+    resourceRef: {
+        id: string;
+        revision: string;
+        digest: {
+            algorithm: "sha256";
+            hex: string;
+        };
+    };
+    action: "cleanup" | "reconcile" | "already_confirmed";
+    priorEvidenceRefs: {
+        id: string;
+        revision: string;
+        digest: {
+            algorithm: "sha256";
+            hex: string;
+        };
+    }[];
+}[];
+/** Artifact paths contain only a content hash and a closed extension; user/domain names never enter them. */
+export declare function capabilityArtifactName(ref: Ref, extension: 'json' | 'jsonl' | 'xml' | 'webm' | 'png' | 'zip' | 'txt'): string;
+export declare function capabilityIdentitySlugs(bindingValue: unknown): {
+    scenario: string;
+    run: string;
+    attempt: string;
+};
+export declare function validateCapabilityArtifactManifest(value: unknown, currentValue: unknown): {
+    schemaVersion: "workflow.capability-artifact-manifest/v1";
+    binding: {
+        campaignId: string;
+        executionId: string;
+        attemptId: string;
+        generation: number;
+        requestRef: {
+            id: string;
+            revision: string;
+            digest: {
+                algorithm: "sha256";
+                hex: string;
+            };
+        };
+        sourceSelectionRef: {
+            id: string;
+            revision: string;
+            digest: {
+                algorithm: "sha256";
+                hex: string;
+            };
+        } | null;
+        caseRef: {
+            id: string;
+            revision: string;
+            digest: {
+                algorithm: "sha256";
+                hex: string;
+            };
+        };
+        personaRef: {
+            id: string;
+            revision: string;
+            digest: {
+                algorithm: "sha256";
+                hex: string;
+            };
+        };
+        targetRef: {
+            id: string;
+            revision: string;
+            digest: {
+                algorithm: "sha256";
+                hex: string;
+            };
+        };
+        environmentRef: {
+            id: string;
+            revision: string;
+            digest: {
+                algorithm: "sha256";
+                hex: string;
+            };
+        };
+        scope: {
+            ownerId: string;
+            tenantId: string | null;
+            visibility: "public" | "owner_private" | "tenant_private";
+        };
+    };
+    publication: "incomplete" | "committed";
+    artifacts: {
+        fileName: string;
+        artifact: {
+            ref: {
+                id: string;
+                revision: string;
+                digest: {
+                    algorithm: "sha256";
+                    hex: string;
+                };
+            };
+            mediaType: string;
+            byteCount: number;
+            producer: {
+                adapterId: string;
+                adapterVersion: string;
+                tool: string;
+                toolVersion: string;
+            };
+            redaction: "not_required" | "applied" | "unavailable";
+            redactionPolicyRef: {
+                id: string;
+                revision: string;
+                digest: {
+                    algorithm: "sha256";
+                    hex: string;
+                };
+            } | null;
+        };
+    }[];
+};
+/** Explicit replay semantics; support must come from the host, never a caller's mode label. */
+export declare function validateCapabilityReplay(value: unknown, supportedModes?: readonly string[]): {
+    schemaVersion: "workflow.capability-replay-plan/v1";
+    mode: "evidence_playback" | "fixture_rerun" | "recorded_io_rerun" | "workflow_history_replay";
+    sourceReceiptRef: {
+        id: string;
+        revision: string;
+        digest: {
+            algorithm: "sha256";
+            hex: string;
+        };
+    };
+    sourceBinding: {
+        campaignId: string;
+        executionId: string;
+        attemptId: string;
+        generation: number;
+        requestRef: {
+            id: string;
+            revision: string;
+            digest: {
+                algorithm: "sha256";
+                hex: string;
+            };
+        };
+        sourceSelectionRef: {
+            id: string;
+            revision: string;
+            digest: {
+                algorithm: "sha256";
+                hex: string;
+            };
+        } | null;
+        caseRef: {
+            id: string;
+            revision: string;
+            digest: {
+                algorithm: "sha256";
+                hex: string;
+            };
+        };
+        personaRef: {
+            id: string;
+            revision: string;
+            digest: {
+                algorithm: "sha256";
+                hex: string;
+            };
+        };
+        targetRef: {
+            id: string;
+            revision: string;
+            digest: {
+                algorithm: "sha256";
+                hex: string;
+            };
+        };
+        environmentRef: {
+            id: string;
+            revision: string;
+            digest: {
+                algorithm: "sha256";
+                hex: string;
+            };
+        };
+        scope: {
+            ownerId: string;
+            tenantId: string | null;
+            visibility: "public" | "owner_private" | "tenant_private";
+        };
+    };
+    targetBinding: {
+        campaignId: string;
+        executionId: string;
+        attemptId: string;
+        generation: number;
+        requestRef: {
+            id: string;
+            revision: string;
+            digest: {
+                algorithm: "sha256";
+                hex: string;
+            };
+        };
+        sourceSelectionRef: {
+            id: string;
+            revision: string;
+            digest: {
+                algorithm: "sha256";
+                hex: string;
+            };
+        } | null;
+        caseRef: {
+            id: string;
+            revision: string;
+            digest: {
+                algorithm: "sha256";
+                hex: string;
+            };
+        };
+        personaRef: {
+            id: string;
+            revision: string;
+            digest: {
+                algorithm: "sha256";
+                hex: string;
+            };
+        };
+        targetRef: {
+            id: string;
+            revision: string;
+            digest: {
+                algorithm: "sha256";
+                hex: string;
+            };
+        };
+        environmentRef: {
+            id: string;
+            revision: string;
+            digest: {
+                algorithm: "sha256";
+                hex: string;
+            };
+        };
+        scope: {
+            ownerId: string;
+            tenantId: string | null;
+            visibility: "public" | "owner_private" | "tenant_private";
+        };
+    } | null;
+    sourceCodeRef: {
+        id: string;
+        revision: string;
+        digest: {
+            algorithm: "sha256";
+            hex: string;
+        };
+    };
+    targetCodeRef: {
+        id: string;
+        revision: string;
+        digest: {
+            algorithm: "sha256";
+            hex: string;
+        };
+    };
+    compatibilityReviewRef: {
+        id: string;
+        revision: string;
+        digest: {
+            algorithm: "sha256";
+            hex: string;
+        };
+    } | null;
+    pins: {
+        fixtureRef: {
+            id: string;
+            revision: string;
+            digest: {
+                algorithm: "sha256";
+                hex: string;
+            };
+        };
+        seedRef: {
+            id: string;
+            revision: string;
+            digest: {
+                algorithm: "sha256";
+                hex: string;
+            };
+        };
+        generatorRef: {
+            id: string;
+            revision: string;
+            digest: {
+                algorithm: "sha256";
+                hex: string;
+            };
+        };
+        runtimeRef: {
+            id: string;
+            revision: string;
+            digest: {
+                algorithm: "sha256";
+                hex: string;
+            };
+        };
+        configRef: {
+            id: string;
+            revision: string;
+            digest: {
+                algorithm: "sha256";
+                hex: string;
+            };
+        };
+        clockMode: "wall" | "frozen" | "engine_virtual";
+        clockRef: {
+            id: string;
+            revision: string;
+            digest: {
+                algorithm: "sha256";
+                hex: string;
+            };
+        };
+    };
+    freshFixtureRefs: {
+        id: string;
+        revision: string;
+        digest: {
+            algorithm: "sha256";
+            hex: string;
+        };
+    }[];
+    historyRef: {
+        id: string;
+        revision: string;
+        digest: {
+            algorithm: "sha256";
+            hex: string;
+        };
+    } | null;
+    externalEffects: "none" | "declared_isolated";
+};

package/dist/core/capabilityLifecycle.js

@@ -0,0 +1,79 @@
+/** Pure lifecycle decisions. No retries, reset, filesystem access or cleanup is performed here. */
+import { CapabilityReplayPlan, CapabilityRetryPolicy, CapabilityRetryState, CapabilityLifecycleCheckpoint, CapabilityArtifactManifest, ScopedResource, CapabilityBinding, digestOfValue, sameRef } from "../protocol/index.js";
+import { CapabilityBoundaryError } from "./capabilityBoundary.js";
+const same = (a, b) => digestOfValue(a).hex === digestOfValue(b).hex;
+export function planCapabilityRetry(policyValue, stateValue) {
+    const policy = CapabilityRetryPolicy.parse(policyValue);
+    const state = CapabilityRetryState.parse(stateValue);
+    const result = (decision, reason, delayMs = null) => ({ decision, reason, delayMs,
+        priorAttemptRef: structuredClone(state.priorAttemptRef), retainedArtifactRefs: structuredClone(state.retainedArtifactRefs) });
+    if (state.effects === 'ambiguous')
+        return result('reconcile', 'effect_outcome_ambiguous');
+    if (['assertion', 'cancelled', 'unsupported'].includes(state.failure))
+        return result('stop', 'failure_not_automatically_retryable');
+    if (state.mutating && state.effects === 'acknowledged' && !state.idempotency)
+        return result('reconcile', 'idempotency_authority_required');
+    if (state.attemptNumber >= policy.maxAttempts || state.requestsUsed >= policy.maxRequests)
+        return result('stop', 'attempt_or_request_budget_exhausted');
+    const delay = Math.max(policy.baseDelayMs * 2 ** Math.min(state.attemptNumber - 1, 10), state.retryAfterMs ?? 0);
+    if (delay > policy.maxDelayMs || state.elapsedMs + delay >= policy.maxElapsedMs || delay >= state.remainingDeadlineMs)
+        return result('stop', 'retry_delay_exceeds_budget');
+    return result('retry', 'transport_or_setup_retry', delay);
+}
+/** Resolve inventory against host-owned records. Ambiguity/staleness always needs reconciliation. */
+export function planCapabilityTeardown(checkpointValue, currentValue, ownedValues, now = Date.now()) {
+    const checkpoint = CapabilityLifecycleCheckpoint.parse(checkpointValue);
+    const current = CapabilityBinding.parse(currentValue);
+    if (!same(checkpoint.binding, current))
+        throw new CapabilityBoundaryError('stale_or_cross_run_cleanup');
+    const owned = ownedValues.map(value => ScopedResource.parse(value));
+    return checkpoint.inventory.map(item => {
+        const resource = owned.find(value => sameRef(value.ref, item.resourceRef));
+        const bound = resource && same(resource.binding, current) && sameRef(resource.leaseRef, item.leaseRef) && resource.isolation === 'owned_isolated' && resource.identityRef !== null && Date.parse(resource.expiresAt) > now;
+        const action = !bound || ['reserved', 'effect_unacknowledged'].includes(item.state) ? 'reconcile'
+            : item.state === 'removed' ? 'already_confirmed' : 'cleanup';
+        return { resourceRef: structuredClone(item.resourceRef), action, priorEvidenceRefs: structuredClone(item.evidenceRefs) };
+    });
+}
+/** Artifact paths contain only a content hash and a closed extension; user/domain names never enter them. */
+export function capabilityArtifactName(ref, extension) {
+    const name = `${ref.digest.hex}.${extension}`;
+    if (!/^[a-f0-9]{64}\.(?:json|jsonl|xml|webm|png|zip|txt)$/.test(name))
+        throw new CapabilityBoundaryError('unsafe_artifact_name');
+    return name;
+}
+export function capabilityIdentitySlugs(bindingValue) {
+    const binding = CapabilityBinding.parse(bindingValue);
+    return { scenario: `scenario-${digestOfValue(binding.caseRef.id).hex.slice(0, 16)}`,
+        run: `run-${digestOfValue({ campaignId: binding.campaignId, executionId: binding.executionId }).hex.slice(0, 16)}`,
+        attempt: `attempt-${digestOfValue({ executionId: binding.executionId, attemptId: binding.attemptId, generation: binding.generation }).hex.slice(0, 16)}` };
+}
+export function validateCapabilityArtifactManifest(value, currentValue) {
+    const manifest = CapabilityArtifactManifest.parse(value);
+    const current = CapabilityBinding.parse(currentValue);
+    if (!same(manifest.binding, current))
+        throw new CapabilityBoundaryError('stale_or_cross_run_artifact_manifest');
+    return structuredClone(manifest);
+}
+/** Explicit replay semantics; support must come from the host, never a caller's mode label. */
+export function validateCapabilityReplay(value, supportedModes = ['evidence_playback']) {
+    const plan = CapabilityReplayPlan.parse(value);
+    if (!supportedModes.includes(plan.mode))
+        throw new CapabilityBoundaryError('unsupported_replay_mode');
+    if (plan.mode === 'evidence_playback') {
+        if (plan.targetBinding || plan.freshFixtureRefs.length || plan.externalEffects !== 'none' || !sameRef(plan.sourceCodeRef, plan.targetCodeRef))
+            throw new CapabilityBoundaryError('playback_must_not_execute_actions');
+    }
+    else {
+        if (!plan.targetBinding || plan.targetBinding.executionId === plan.sourceBinding.executionId || plan.targetBinding.attemptId === plan.sourceBinding.attemptId || !plan.freshFixtureRefs.length)
+            throw new CapabilityBoundaryError('rerun_requires_fresh_attempt_and_fixtures');
+        if (plan.freshFixtureRefs.some(ref => ref.id === plan.pins.fixtureRef.id) || new Set(plan.freshFixtureRefs.map(ref => ref.id)).size !== plan.freshFixtureRefs.length)
+            throw new CapabilityBoundaryError('rerun_requires_distinct_fresh_fixtures');
+        if (plan.targetBinding.scope.ownerId !== plan.sourceBinding.scope.ownerId || !same(plan.targetBinding.scope, plan.sourceBinding.scope))
+            throw new CapabilityBoundaryError('replay_scope_mismatch');
+        if (plan.mode === 'workflow_history_replay' && (!plan.historyRef || (!sameRef(plan.sourceCodeRef, plan.targetCodeRef) && !plan.compatibilityReviewRef)))
+            throw new CapabilityBoundaryError('history_code_compatibility_unreviewed');
+    }
+    return structuredClone(plan); // No replay/provider operation is performed.
+}
+//# sourceMappingURL=capabilityLifecycle.js.map

package/dist/core/capabilityLifecycle.js.map

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

package/dist/core/cleanup.d.ts

@@ -0,0 +1,35 @@
+import { type ActionRegistry, type CleanupObservation } from '../protocol/index.ts';
+import type { HttpDriver } from '../adapters/http/driver.ts';
+import type { HostSession } from '../hosts/types.ts';
+import type { Deadline } from './deadline.ts';
+import type { EventLog } from './events.ts';
+export type AllocatedFixture = {
+    entityKey: string;
+    physicalId: string;
+    cleanup: {
+        actionId: string;
+        args: Record<string, unknown>;
+    } | null;
+    absence: {
+        actionId: string;
+        expectStatus: number;
+    } | null;
+};
+/** Collect observed cleanup only. This report is not an authority to release a hosted lease. */
+export declare function collectCleanup(input: {
+    allocated: readonly AllocatedFixture[];
+    uncertainAllocations: number;
+    uncertainOperations?: number;
+    registry: ActionRegistry | null;
+    driver: Pick<HttpDriver, 'request'> | null;
+    origin: string;
+    deadline: Deadline;
+    session: HostSession | null;
+    reason: string;
+    log: Pick<EventLog, 'emit'>;
+}): Promise<{
+    cleanup: CleanupObservation;
+    criticalCleanupConfirmed: boolean;
+    confirmedFixtureKeys: string[];
+    hostCleanupConfirmed: boolean;
+}>;

package/dist/core/cleanup.js

@@ -0,0 +1,71 @@
+import { CleanupObservation as CleanupSchema } from "../protocol/index.js";
+import { cleanupActionError } from "./cleanupActions.js";
+/** Collect observed cleanup only. This report is not an authority to release a hosted lease. */
+export async function collectCleanup(input) {
+    const { allocated, driver, registry, origin, deadline, session, log } = input;
+    const attempted = [];
+    const confirmed = [];
+    for (const entry of [...allocated].reverse()) {
+        if (!entry.cleanup || !driver || !registry) {
+            log.emit('cleanup.entity', null, { entityKey: entry.entityKey, confirmed: false, reason: 'cleanup_unavailable' });
+            continue;
+        }
+        attempted.push(entry.entityKey);
+        try {
+            const action = registry.actions.find(item => item.actionId === entry.cleanup.actionId);
+            const absenceAction = registry.actions.find(item => item.actionId === entry.absence?.actionId);
+            const error = cleanupActionError(action, absenceAction, entry.absence?.expectStatus ?? 0);
+            if (error)
+                throw new Error(error);
+            if (!action || !entry.absence || !absenceAction)
+                throw new Error('cleanup actions unavailable');
+            const result = await driver.request({ origin, method: action.method, path: action.path, body: action.body,
+                auth: action.auth, variables: entry.cleanup.args, deadline: deadline.child(5000) });
+            const readback = await driver.request({ origin, method: absenceAction.method, path: absenceAction.path,
+                body: absenceAction.body, auth: absenceAction.auth, variables: entry.cleanup.args, deadline: deadline.child(5000) });
+            const absent = readback.status === entry.absence.expectStatus;
+            const ok = (action.expectStatus === null || result.status === action.expectStatus) && absent;
+            if (ok)
+                confirmed.push(entry.entityKey);
+            log.emit('cleanup.entity', null, { entityKey: entry.entityKey, status: result.status,
+                absenceConfirmed: absent, confirmed: ok });
+        }
+        catch (error) {
+            log.emit('cleanup.entity', null, { entityKey: entry.entityKey, confirmed: false,
+                error: error instanceof Error ? error.message : 'cleanup failed' });
+        }
+    }
+    let hostStopConfirmed = false;
+    if (session) {
+        try {
+            const stop = await session.stop(input.reason);
+            hostStopConfirmed = stop.confirmed;
+            log.emit('cleanup.host', null, { confirmed: stop.confirmed, detail: stop.detail });
+        }
+        catch (error) {
+            log.emit('cleanup.host', null, { confirmed: false, detail: error instanceof Error ? error.message : 'host cleanup failed' });
+        }
+    }
+    // Every allocation remains unresolved until observed cleanup, including those
+    // lacking handles. A lost allocation response cannot invent a physical ID.
+    const unconfirmed = allocated.filter(item => !confirmed.includes(item.entityKey)).length;
+    const unknown = unconfirmed + input.uncertainAllocations + (input.uncertainOperations ?? 0);
+    const hostResources = session?.ownedResources ?? [];
+    const cleanup = CleanupSchema.parse({
+        ownedResources: [...allocated.map(item => ({ entityKey: item.entityKey, physicalId: item.physicalId, boundaryId: 'application' })), ...hostResources],
+        attempted: [...attempted, ...hostResources.map(item => item.entityKey)],
+        confirmed: [...confirmed, ...(hostStopConfirmed ? hostResources.map(item => item.entityKey) : [])],
+        remainingUnknownMutations: unknown,
+        critical: [...allocated.map(item => item.entityKey), ...hostResources.map(item => item.entityKey)],
+        janitorReceiptRef: null,
+        reasonCodes: [...(unconfirmed ? ['fixture_cleanup_unconfirmed'] : []),
+            ...(input.uncertainAllocations ? ['fixture_allocation_uncertain'] : []),
+            ...(input.uncertainOperations ? ['operation_outcome_uncertain'] : []),
+            ...(session && !hostStopConfirmed ? ['host_stop_unconfirmed'] : [])],
+    });
+    // Typed acknowledgement provenance is separate from the legacy public display-key arrays.
+    // A fixture key may equal a host key; neither can acknowledge the other resource kind.
+    return { cleanup, criticalCleanupConfirmed: unknown === 0 && (!session || hostStopConfirmed),
+        confirmedFixtureKeys: [...confirmed], hostCleanupConfirmed: hostStopConfirmed };
+}
+//# sourceMappingURL=cleanup.js.map

package/dist/core/cleanup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup.js","sourceRoot":"","sources":["../../src/core/cleanup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,IAAI,aAAa,EAAgD,MAAM,sBAAsB,CAAC;AAKzH,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAQzD,gGAAgG;AAChG,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,KAKpC;IACC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,KAAK,CAAC;IAC9E,MAAM,SAAS,GAAa,EAAE,CAAC;IAAC,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/D,KAAK,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;QAC7C,IAAI,CAAC,KAAK,CAAC,OAAO,IAAI,CAAC,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC3C,GAAG,CAAC,IAAI,CAAC,gBAAgB,EAAE,IAAI,EAAE,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,qBAAqB,EAAE,CAAC,CAAC;YAClH,SAAS;QACX,CAAC;QACD,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QAChC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,KAAK,KAAK,CAAC,OAAQ,CAAC,QAAQ,CAAC,CAAC;YACxF,MAAM,aAAa,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,KAAK,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;YAC/F,MAAM,KAAK,GAAG,kBAAkB,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,CAAC,OAAO,EAAE,YAAY,IAAI,CAAC,CAAC,CAAC;YAC1F,IAAI,KAAK;gBAAE,MAAM,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC;YAClC,IAAI,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,IAAI,CAAC,aAAa;gBAAE,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;YAChG,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI;gBACvG,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACtF,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,CAAC,MAAM,EAAE,IAAI,EAAE,aAAa,CAAC,IAAI;gBACpG,IAAI,EAAE,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,aAAa,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACvH,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,KAAK,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC;YAC9D,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,YAAY,KAAK,IAAI,IAAI,MAAM,CAAC,MAAM,KAAK,MAAM,CAAC,YAAY,CAAC,IAAI,MAAM,CAAC;YAC7F,IAAI,EAAE;gBAAE,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;YACxC,GAAG,CAAC,IAAI,CAAC,gBAAgB,EAAE,IAAI,EAAE,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM;gBAClF,gBAAgB,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC;QAC/C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,GAAG,CAAC,IAAI,CAAC,gBAAgB,EAAE,IAAI,EAAE,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK;gBAC7E,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,gBAAgB,EAAE,CAAC,CAAC;QACxE,CAAC;IACH,CAAC;IACD,IAAI,iBAAiB,GAAG,KAAK,CAAC;IAC9B,IAAI,OAAO,EAAE,CAAC;QACZ,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YAC9C,iBAAiB,GAAG,IAAI,CAAC,SAAS,CAAC;YACnC,GAAG,CAAC,IAAI,CAAC,cAAc,EAAE,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QACrF,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,GAAG,CAAC,IAAI,CAAC,cAAc,EAAE,IAAI,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,qBAAqB,EAAE,CAAC,CAAC;QAC/H,CAAC;IACH,CAAC;IACD,8EAA8E;IAC9E,2EAA2E;IAC3E,MAAM,WAAW,GAAG,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC;IACzF,MAAM,OAAO,GAAG,WAAW,GAAG,KAAK,CAAC,oBAAoB,GAAG,CAAC,KAAK,CAAC,mBAAmB,IAAI,CAAC,CAAC,CAAC;IAC5F,MAAM,aAAa,GAAG,OAAO,EAAE,cAAc,IAAI,EAAE,CAAC;IACpD,MAAM,OAAO,GAAG,aAAa,CAAC,KAAK,CAAC;QAClC,cAAc,EAAE,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,UAAU,EAAE,aAAa,EAAE,CAAC,CAAC,EAAE,GAAG,aAAa,CAAC;QACrJ,SAAS,EAAE,CAAC,GAAG,SAAS,EAAE,GAAG,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACvE,SAAS,EAAE,CAAC,GAAG,SAAS,EAAE,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAClG,yBAAyB,EAAE,OAAO;QAClC,QAAQ,EAAE,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAClG,iBAAiB,EAAE,IAAI;QACvB,WAAW,EAAE,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,6BAA6B,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACnE,GAAG,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,8BAA8B,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACvE,GAAG,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,6BAA6B,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACrE,GAAG,CAAC,OAAO,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;KACvE,CAAC,CAAC;IACH,0FAA0F;IAC1F,uFAAuF;IACvF,OAAO,EAAE,OAAO,EAAE,wBAAwB,EAAE,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,OAAO,IAAI,iBAAiB,CAAC;QAC1F,oBAAoB,EAAE,CAAC,GAAG,SAAS,CAAC,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,CAAC;AACpF,CAAC"}

package/dist/core/cleanupActions.d.ts

@@ -0,0 +1,5 @@
+import type { ActionRegistry } from '../protocol/index.ts';
+type Action = ActionRegistry['actions'][number];
+/** The HTTP status-only absence contract requires an explicit missing-resource response. */
+export declare function cleanupActionError(action: Action | undefined, absence: Action | undefined, absenceStatus: number): string | null;
+export {};

package/dist/core/cleanupActions.js

@@ -0,0 +1,15 @@
+/** The HTTP status-only absence contract requires an explicit missing-resource response. */
+export function cleanupActionError(action, absence, absenceStatus) {
+    if (!action || !absence)
+        return 'cleanup requires registered deletion and absence readback';
+    if (action.effect !== 'delete' || ['GET', 'HEAD', 'OPTIONS'].includes(action.method)) {
+        return 'cleanup requires a registered delete effect with a mutating method';
+    }
+    if (absence.effect !== 'read' || !['GET', 'HEAD'].includes(absence.method)) {
+        return 'absence readback requires a registered read effect using GET or HEAD';
+    }
+    if (![404, 410].includes(absenceStatus))
+        return 'status-only absence readback requires 404 or 410';
+    return null;
+}
+//# sourceMappingURL=cleanupActions.js.map

package/dist/core/cleanupActions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanupActions.js","sourceRoot":"","sources":["../../src/core/cleanupActions.ts"],"names":[],"mappings":"AAIA,4FAA4F;AAC5F,MAAM,UAAU,kBAAkB,CAAC,MAA0B,EAAE,OAA2B,EACxF,aAAqB;IACrB,IAAI,CAAC,MAAM,IAAI,CAAC,OAAO;QAAE,OAAO,2DAA2D,CAAC;IAC5F,IAAI,MAAM,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;QACrF,OAAO,oEAAoE,CAAC;IAC9E,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,IAAI,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3E,OAAO,sEAAsE,CAAC;IAChF,CAAC;IACD,IAAI,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC;QAAE,OAAO,kDAAkD,CAAC;IACnG,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/core/cleanupAttestation.d.ts

@@ -0,0 +1,23 @@
+import { type KeyObject } from 'node:crypto';
+import { type CleanupExpectation, type SignedCleanupFollowup } from '../protocol/schemas/cleanup.ts';
+export declare function cleanupExpectationDigest(raw: unknown): string;
+/** Only an independent collector holding its protected signing key may issue this follow-up. */
+export declare function signCleanupFollowup(raw: unknown, keyId: string, privateKey: KeyObject): SignedCleanupFollowup;
+export type CleanupObserver = {
+    scopeId: string;
+    observerId: string;
+    publicKey: KeyObject;
+};
+/**
+ * Integrity and expectation validation only. The storage owner must recheck the
+ * current lease, manifest and time under its admission lock before releasing it.
+ * Signature trust does not establish provider qualification or authorize effects.
+ */
+export declare function verifyCleanupFollowup(raw: unknown, expectedRaw: unknown, input: {
+    trustedObservers: ReadonlyMap<string, CleanupObserver>;
+    observedAt: number;
+}): {
+    followup: SignedCleanupFollowup['followup'];
+    proofDigest: string;
+    expectation: CleanupExpectation;
+};