@sentropic/h2a-runtime 0.98.6 → 0.98.7-rc.1

package/dist/vendor/engram-live/integration.js

@@ -0,0 +1,194 @@
+// Vendored from @sentropic/engram-live 0.1.0 dist/integration.js — same
+// provenance as the sibling contracts.js header (graphify@70ebdfee, pinned
+// tarball sha512 in the GUARD test). Only the derive* re-exports are
+// consumed by H; the factory reads grammars lazily through injected ports.
+// Portable: node: builtins plus siblings only. Do not hand-edit.
+// @sentropic/engram-live/integration — executable neutral factory
+// (spec/SPEC_LIVE_GIT_INDEXING.md §2–3, §11; plan/09 L1b).
+//
+// The factory composes injected capabilities only: Git, filesystem, clock,
+// content, fact-sink, cache and grammar ports. It never imports the
+// monolithic root CLI, another @sentropic/* consumer package, the h2a host,
+// a model module or a storage-driver handle — those stay outside the neutral
+// closure by construction and by tests/live-neutrality.test.ts.
+//
+// L1b supplies the package/factory seams and grammar loading. Every other
+// capability is explicitly unavailable until its lot lands; the factory
+// never fabricates facts, writes through the fact sink or silently
+// degrades an unavailable capability into an empty success.
+import { createHash } from "node:crypto";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ADVERTISED_LANGUAGES, CAPABILITY_IDS, CAPABILITY_PLANNED_LOTS, GRAMMAR_UNAVAILABLE_REASON, NOT_IMPLEMENTED_REASON, validateFactBatch, validateWorkspaceDeclaration, } from "./contracts.js";
+function decodeJson(bytes) {
+    return JSON.parse(new TextDecoder().decode(bytes));
+}
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+// The pinned manifest is validated before any grammar is trusted: a
+// manifestVersion number and a languages record whose entries pin a
+// non-empty file and sha256 are required.
+function isGrammarManifest(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    if (typeof candidate.manifestVersion !== "number")
+        return false;
+    if (typeof candidate.languages !== "object" || candidate.languages === null || Array.isArray(candidate.languages)) {
+        return false;
+    }
+    return Object.values(candidate.languages).every((entry) => {
+        if (typeof entry !== "object" || entry === null)
+            return false;
+        const record = entry;
+        return typeof record.file === "string" && record.file.length > 0
+            && typeof record.sha256 === "string" && record.sha256.length > 0;
+    });
+}
+export function createLiveFactory(options) {
+    const declarationCheck = validateWorkspaceDeclaration(options.declaration);
+    if (!declarationCheck.ok) {
+        throw new Error(`invalid live workspace declaration: ${declarationCheck.errors.join("; ")}`);
+    }
+    const ports = options.ports;
+    const distDir = dirname(fileURLToPath(import.meta.url));
+    const manifestPath = join(distDir, "..", "grammar-manifest.json");
+    const grammarDir = join(distDir, "grammars");
+    let manifestCache;
+    const loadManifest = async () => {
+        if (manifestCache)
+            return { ok: true, manifest: manifestCache };
+        let decoded;
+        try {
+            decoded = decodeJson(await ports.filesystem.readFileBytes(manifestPath));
+        }
+        catch (error) {
+            return {
+                ok: false,
+                reason: `the pinned grammar manifest cannot be read through the filesystem port (${errorMessage(error)})`,
+            };
+        }
+        if (!isGrammarManifest(decoded)) {
+            return {
+                ok: false,
+                reason: "the pinned grammar manifest is invalid: a manifestVersion number and a languages record pinning file/sha256 entries are required",
+            };
+        }
+        manifestCache = decoded;
+        return { ok: true, manifest: decoded };
+    };
+    const grammarLoadCache = new Map();
+    return {
+        describeCapabilities() {
+            return CAPABILITY_IDS.map((capability) => ({
+                capability,
+                state: "unavailable",
+                reason: NOT_IMPLEMENTED_REASON,
+                plannedLot: CAPABILITY_PLANNED_LOTS[capability],
+            }));
+        },
+        async runCapability(capability) {
+            if (!CAPABILITY_IDS.includes(capability)) {
+                throw new Error(`unknown capability "${String(capability)}"; known capabilities: ${CAPABILITY_IDS.join(", ")}`);
+            }
+            // Explicit unavailability: no port call, no fabricated facts, no
+            // empty-success degradation.
+            return {
+                capability,
+                state: "unavailable",
+                reason: NOT_IMPLEMENTED_REASON,
+                plannedLot: CAPABILITY_PLANNED_LOTS[capability],
+                delivered: false,
+            };
+        },
+        grammarCoverage(language) {
+            // Synchronous coverage uses the pinned manifest; loadGrammar caches the
+            // executed result per language so coverage reflects verified assets.
+            const loaded = grammarLoadCache.get(language);
+            if (loaded?.state === "available") {
+                return { axis: "ast", language, state: "current", reason: `packaged grammar verified (sha256 ${loaded.bytesSha256})` };
+            }
+            return {
+                axis: "ast",
+                language,
+                state: "unavailable",
+                reason: `${GRAMMAR_UNAVAILABLE_REASON}: "${language}" has no verified packaged grammar in this session`,
+            };
+        },
+        grammarCoverageReport(language) {
+            const coverage = this.grammarCoverage(language);
+            return {
+                axis: coverage.axis,
+                language,
+                state: coverage.state,
+                reason: coverage.reason,
+                checkedAt: ports.clock.now(),
+            };
+        },
+        async loadGrammar(language) {
+            const cached = grammarLoadCache.get(language);
+            if (cached)
+                return cached;
+            const unavailable = (reason) => {
+                const result = { language, state: "unavailable", reason };
+                grammarLoadCache.set(language, result);
+                return result;
+            };
+            // Reading and validating the manifest is part of the load: an absent,
+            // unreadable or invalid manifest yields an explicit unavailable result,
+            // never a thrown error and never a silent empty success.
+            const manifestOutcome = await loadManifest();
+            if (!manifestOutcome.ok || manifestOutcome.manifest === undefined) {
+                return unavailable(`${GRAMMAR_UNAVAILABLE_REASON}: ${manifestOutcome.reason ?? "the pinned grammar manifest is unavailable"}`);
+            }
+            // Clean own-property lookup: inherited names such as "constructor" or
+            // "toString" never reach a manifest entry.
+            if (!Object.hasOwn(manifestOutcome.manifest.languages, language)) {
+                return unavailable(`${GRAMMAR_UNAVAILABLE_REASON}: "${language}" is absent from the pinned grammar manifest`);
+            }
+            const entry = manifestOutcome.manifest.languages[language];
+            let bytes;
+            try {
+                bytes = await ports.filesystem.readFileBytes(join(grammarDir, entry.file));
+            }
+            catch (error) {
+                return unavailable(`${GRAMMAR_UNAVAILABLE_REASON}: the packaged WASM for "${language}" cannot be read through the filesystem port (${errorMessage(error)})`);
+            }
+            const digest = sha256(bytes);
+            if (digest !== entry.sha256) {
+                return unavailable(`packaged grammar digest mismatch for "${language}": pinned ${entry.sha256}, read ${digest}`);
+            }
+            try {
+                const grammar = await ports.grammarRuntime.loadLanguage(bytes);
+                const result = {
+                    language,
+                    state: "available",
+                    bytesSha256: digest,
+                    grammar,
+                };
+                grammarLoadCache.set(language, result);
+                return result;
+            }
+            catch (error) {
+                return unavailable(`grammar runtime rejected the packaged WASM for "${language}": ${errorMessage(error)}`);
+            }
+        },
+        validateBatch(batch) {
+            return validateFactBatch(batch);
+        },
+    };
+}
+/** The advertised grammar matrix of this build, from the pinned manifest data. */
+export const ADVERTISED_GRAMMAR_LANGUAGES = ADVERTISED_LANGUAGES;
+// The canonical identity derivation (L6a, spec §3/§12) is part of the public
+// integration surface: h2a and cluster-mesh mint cloneId/worktreeId/
+// declarationId through exactly these functions, so every seat derives
+// byte-identical opaque ids from identical components. The minting needs
+// node:crypto (sha256), which keeps it out of the data-pure /contracts
+// entry; the derivation itself stays pure and deterministic over its
+// arguments (see ./registration.js).
+export { deriveCloneIdentity, deriveWorktreeIdentity, deriveDeclarationIdentity, } from "./registration.js";

package/dist/vendor/engram-live/registration.d.ts

@@ -0,0 +1,138 @@
+// Vendored types for the sibling .js — see its provenance header; do not hand-edit.
+import { type CloneIdentityDto, type DeclarationRevocationDto, type IdentityUncertaintyState, type NonActivatingLifecycleKind, type OidAlgorithm, type RevocationReason, type WorkspaceDeclarationDto, type WorktreeIdentityDto } from "./contracts.js";
+/** Input for an explicit live declaration (revision starts at INITIAL_DECLARATION_REVISION). */
+export interface CreateLiveDeclarationInput {
+    readonly tenant: string;
+    readonly principal: string;
+    readonly hostFingerprint?: string;
+    readonly identityUncertainty: readonly IdentityUncertaintyState[];
+    readonly declarationId: string;
+    readonly cloneId: string;
+    readonly worktreeId: string;
+    readonly authorizedRoots: readonly string[];
+    readonly liveCapability: "live";
+    readonly policyVersion: string;
+    readonly serverWorkspaceId?: string;
+    readonly serverIssuer?: string;
+    readonly bindingRevision?: number;
+}
+/** Patchable declaration fields. Identity (tenant, principal,
+ * hostFingerprint, the declarationId/cloneId/worktreeId triangle,
+ * liveCapability, declarationRevision) is immutable across revisions. */
+export interface LiveDeclarationPatch {
+    readonly authorizedRoots?: readonly string[];
+    readonly policyVersion?: string;
+    readonly serverWorkspaceId?: string;
+    readonly serverIssuer?: string;
+    readonly bindingRevision?: number;
+}
+/** Input for deriving a clone identity from host-resolved components. */
+export interface DeriveCloneIdentityInput {
+    readonly hostScope: string;
+    readonly commonDirRealpath: string;
+    readonly commonDirProjectFingerprint?: string;
+    readonly identityUncertainty?: readonly IdentityUncertaintyState[];
+    readonly oidAlgorithm: OidAlgorithm;
+}
+/** Input for deriving a worktree identity under an already derived clone. */
+export interface DeriveWorktreeIdentityInput {
+    readonly hostScope: string;
+    readonly clone: Pick<CloneIdentityDto, "cloneId">;
+    readonly worktreePath: string;
+    readonly gitDir: string;
+    readonly worktreeFingerprint?: string;
+    readonly identityUncertainty?: readonly IdentityUncertaintyState[];
+}
+/** Input for deriving the identity of one declaration under a clone/worktree. */
+export interface DeriveDeclarationIdentityInput {
+    readonly hostScope: string;
+    readonly clone: Pick<CloneIdentityDto, "cloneId">;
+    readonly worktree: Pick<WorktreeIdentityDto, "worktreeId">;
+}
+/** Opaque declaration identity: the declaration and its clone/worktree attachment. */
+export interface DeclarationIdentityDto {
+    readonly declarationId: string;
+    readonly cloneId: string;
+    readonly worktreeId: string;
+}
+/**
+ * Create the initial live declaration for one workspace. Requires the
+ * explicit "live" capability and the full identity triangle
+ * (declarationId/cloneId/worktreeId, minted by the canonical derivation
+ * below): any other opt-in value (bind, upload, session kinds) is refused,
+ * so no lifecycle event can implicitly activate live. The declaration
+ * revision starts at the frozen INITIAL_DECLARATION_REVISION.
+ */
+export declare function createLiveDeclaration(input: CreateLiveDeclarationInput): WorkspaceDeclarationDto;
+/**
+ * Revise a declaration as a pure revision increment. The revision grows by
+ * exactly one; tenant, principal, hostFingerprint, the identity triangle
+ * and the live capability are immutable. The product binding is the
+ * complete (serverWorkspaceId, serverIssuer, bindingRevision) triplet.
+ * A revision outside the binding (roots, policy version) PRESERVES the
+ * binding: no renewal is imposed. Only a change of serverWorkspaceId or
+ * serverIssuer, or an explicit bindingRevision revalidation, renews the
+ * binding — and then strictly increasingly: the first binding carries
+ * exactly INITIAL_BINDING_REVISION, and every rebind/revalidation carries
+ * a strictly greater bindingRevision; binding revisions never go
+ * backwards. The host must additionally refuse to redirect in-flight
+ * collection/publication when a rebind lands.
+ */
+export declare function reviseLiveDeclaration(previous: WorkspaceDeclarationDto, patch: LiveDeclarationPatch): WorkspaceDeclarationDto;
+/**
+ * Revoke exactly one declaration as a pure private-purge request. The
+ * returned DTO names the single target by its opaque declarationId and
+ * carries the declaration's cloneId/worktreeId attachment and revision, so
+ * the recipient can never confuse two declarations of one tenant that
+ * happen to share public fingerprints or revisions. The host stops work,
+ * rejects delayed jobs and purges private snapshots, derived indexes and
+ * decryptability, while preserving authorized committed history.
+ * Revocation deletes no committed facts.
+ */
+export declare function revokeLiveDeclaration(declaration: WorkspaceDeclarationDto, reason: RevocationReason): DeclarationRevocationDto;
+/**
+ * Derive the clone identity for one common-dir — the ONE canonical clone
+ * derivation. The key components (hostScope, normalized common-dir
+ * realpath, common-dir project fingerprint) serialize through
+ * canonicalIdKey (unambiguous, NUL-refusing) and hash to the opaque
+ * cloneId: equal fingerprints under different realpaths derive distinct
+ * clones, while linked worktrees sharing one common-dir derive the same
+ * clone. The fingerprint may be absent only under explicit
+ * "missing_history" uncertainty; the hostScope + realpath components keep
+ * clones distinct even then (LIVE §12). The realpath stays host-local;
+ * only cloneId is shared. Deterministic and free of I/O.
+ */
+export declare function deriveCloneIdentity(input: DeriveCloneIdentityInput): CloneIdentityDto;
+/**
+ * Derive the identity of one worktree under an already derived clone —
+ * the ONE canonical worktree derivation. Worktrees of one clone share
+ * cloneId and keep an isolated host-scoped worktreeId plus per-worktree
+ * git-dir, fingerprint and path. The worktree fingerprint may be absent
+ * only under explicit "missing_history" uncertainty (LIVE §12).
+ */
+export declare function deriveWorktreeIdentity(input: DeriveWorktreeIdentityInput): WorktreeIdentityDto;
+/**
+ * Derive the identity of one declaration — the ONE canonical declaration
+ * derivation. One declaration per activated worktree: the declarationId
+ * binds the host scope, the clone and the worktree, so two worktrees of
+ * one clone (and two clones of one project) derive distinct declarationIds
+ * even without fingerprints. Stable across every revision of the same
+ * declaration. Deterministic and free of I/O.
+ */
+export declare function deriveDeclarationIdentity(input: DeriveDeclarationIdentityInput): DeclarationIdentityDto;
+/**
+ * Decide whether two clone references denote the same clone, by canonical
+ * identifier only: the cloneId minted by the shared canonical derivation is
+ * the clone identity, so the comparison is an equivalence (transitive and
+ * consistent between full DTOs and opaque references). Throws when either
+ * reference lacks a cloneId — equality is never guessed from components.
+ */
+export declare function isSameClone(a: Pick<CloneIdentityDto, "cloneId">, b: Pick<CloneIdentityDto, "cloneId">): boolean;
+/**
+ * Classify a host lifecycle event against live declarations. Bind, upload,
+ * code-workspace creation and session open/end never activate or remove a
+ * declaration: the only outcome is "no-activation-change". Unknown kinds
+ * are refused.
+ */
+export declare function classifyLifecycleEvent(kind: NonActivatingLifecycleKind): "no-activation-change";
+//# sourceMappingURL=registration.d.ts.map