instar 1.3.1113 → 1.3.1115

package/dist/core/CartographerRootAuthority.js

@@ -0,0 +1,448 @@
+/**
+ * CartographerRootAuthority — inert root-selection and verification substrate.
+ *
+ * This module deliberately does not wire itself into Cartographer routes or the
+ * freshness sweep. It separates three questions that the old projectDir
+ * singleton collapsed:
+ *
+ *   1. Which root did a provenance-bearing source select?
+ *   2. What repository identity and revision are actually present there?
+ *   3. Which operations are safe at the resulting trust level?
+ *
+ * A selected directory without a readable Git HEAD remains useful for the
+ * zero-cost structural hierarchy, but it is never eligible for paid authoring.
+ * Contradictory evidence (for example an expected-remote mismatch) refuses the
+ * root entirely. PR 11B-2 is the consumer boundary that will apply this contract
+ * to live navigation, reporting, and authoring.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { SafeGitExecutor } from './SafeGitExecutor.js';
+const GIT_OP = 'cartographer-root-authority';
+/**
+ * Select a candidate only from an explicit, typed provenance source.
+ *
+ * In particular, a standalone active-project request never falls back to the
+ * agent home. That fallback is the wrong-root failure this contract exists to
+ * remove. Instar source is explicit-only: directory scanning and marker files
+ * may corroborate an identity later, but can never select it.
+ */
+export function selectCartographerRootCandidate(request) {
+    if (request.kind === 'agent-home') {
+        return {
+            ok: true,
+            candidate: {
+                kind: request.kind,
+                requestedPath: request.agentHome,
+                provenance: { source: 'agent-home', agentName: request.agentName },
+            },
+        };
+    }
+    if (request.kind === 'instar-source-checkout') {
+        if (!request.binding?.projectDir || !request.binding.gitRemote) {
+            return {
+                ok: false,
+                code: 'instar-source-binding-required',
+                message: 'Instar source selection requires an explicit binding with a repository anchor',
+            };
+        }
+        return {
+            ok: true,
+            candidate: {
+                kind: request.kind,
+                requestedPath: request.binding.projectDir,
+                provenance: {
+                    source: 'operator-binding',
+                    bindingId: request.binding.bindingId,
+                    projectName: request.binding.projectName,
+                },
+                expectedRemote: request.binding.gitRemote,
+            },
+        };
+    }
+    if (request.topicBinding) {
+        return {
+            ok: true,
+            candidate: {
+                kind: request.kind,
+                requestedPath: request.topicBinding.projectDir,
+                provenance: {
+                    source: 'topic-binding',
+                    topicId: request.topicBinding.topicId,
+                    projectName: request.topicBinding.projectName,
+                },
+                expectedRemote: request.topicBinding.gitRemote,
+            },
+        };
+    }
+    if (request.standalone) {
+        return {
+            ok: false,
+            code: 'topic-binding-required',
+            message: 'A standalone active-project root requires a topic-project binding',
+        };
+    }
+    if (!request.serverProject) {
+        return {
+            ok: false,
+            code: 'server-project-required',
+            message: 'A project-bound active-project root requires the server project declaration',
+        };
+    }
+    return {
+        ok: true,
+        candidate: {
+            kind: request.kind,
+            requestedPath: request.serverProject.projectDir,
+            provenance: {
+                source: 'server-project',
+                projectName: request.serverProject.projectName,
+            },
+            expectedRemote: request.serverProject.gitRemote,
+        },
+    };
+}
+/** Normalize common HTTPS, SSH, and scp-like Git remote spellings for identity comparison. */
+export function normalizeCartographerGitRemote(raw) {
+    let value = raw.trim();
+    while (value.endsWith('/'))
+        value = value.slice(0, -1);
+    if (/\.git$/i.test(value))
+        value = value.slice(0, -4);
+    const normalizePath = (host, rawPath) => {
+        const clean = rawPath
+            .replace(/^\/+/, '')
+            .replace(/\.git$/i, '')
+            .replace(/\/+$/, '');
+        // github.com documents repository URLs as case-insensitive. Preserve path
+        // case everywhere else: folding an unknown forge's path can collapse two
+        // genuinely different repositories into one trusted identity.
+        return host === 'github.com' ? clean.toLowerCase() : clean;
+    };
+    const scp = value.match(/^(?:[^@/]+@)?([^:/]+):(.+)$/);
+    if (scp && !value.includes('://')) {
+        const host = scp[1].toLowerCase();
+        return `${host}/${normalizePath(host, scp[2])}`;
+    }
+    try {
+        const parsed = new URL(value);
+        const host = parsed.hostname.toLowerCase();
+        const pathname = normalizePath(host, parsed.pathname);
+        if (parsed.protocol === 'file:')
+            return `file:${pathname}`;
+        const defaultPort = (parsed.protocol === 'ssh:' && parsed.port === '22') ||
+            (parsed.protocol === 'git:' && parsed.port === '9418') ||
+            (parsed.protocol === 'http:' && parsed.port === '80') ||
+            (parsed.protocol === 'https:' && parsed.port === '443');
+        const authority = parsed.port && !defaultPort ? `${host}:${parsed.port}` : host;
+        return `${authority}/${pathname}`;
+    }
+    catch {
+        // Unknown syntax is not safe to case-fold. Equality remains available for
+        // byte-equivalent anchors without manufacturing false equivalence.
+        return value;
+    }
+}
+function digest(value, length = 24) {
+    return crypto
+        .createHash('sha256')
+        .update(value, 'utf8')
+        .digest('hex')
+        .slice(0, length);
+}
+function provenanceKey(provenance) {
+    switch (provenance.source) {
+        case 'agent-home':
+            return `agent-home:${provenance.agentName}`;
+        case 'server-project':
+            return `server-project:${provenance.projectName}`;
+        case 'topic-binding':
+            return `topic-binding:${provenance.topicId}:${provenance.projectName}`;
+        case 'operator-binding':
+            return `operator-binding:${provenance.bindingId}:${provenance.projectName}`;
+    }
+}
+function readGit(cwd, args) {
+    try {
+        // Root verification must work against the Instar source checkout itself.
+        // SafeGitExecutor keeps this opt-in narrow: only its closed read-tier verb
+        // allowlist bypasses SourceTreeGuard; a destructive/differently-shaped call
+        // still cannot pass through this option.
+        const value = SafeGitExecutor.readSync(args, {
+            cwd,
+            operation: GIT_OP,
+            sourceTreeReadOk: true,
+        }).trim();
+        return value || null;
+    }
+    catch {
+        return null; /* @silent-fallback-ok — unreadable Git evidence becomes a required structured authority decision */
+    }
+}
+function readRemotes(cwd) {
+    // `remote -v` is on SafeGitExecutor's source-tree read-tier allowlist, while
+    // arbitrary config access intentionally is not. Parse fetch identities only:
+    // a push-only URL proves write destination, not which repository was checked out.
+    const raw = readGit(cwd, ['remote', '-v']);
+    if (!raw)
+        return [];
+    const remotes = [];
+    for (const line of raw.split('\n')) {
+        const match = line.match(/^(\S+)\s+(.+?)\s+\(fetch\)$/);
+        if (!match)
+            continue;
+        const url = match[2].trim();
+        if (!url)
+            continue;
+        remotes.push({
+            name: match[1],
+            url,
+            normalized: normalizeCartographerGitRemote(url),
+        });
+    }
+    return remotes;
+}
+function canonicalCommonGitDir(cwd) {
+    const raw = readGit(cwd, ['rev-parse', '--git-common-dir']);
+    if (!raw)
+        return null;
+    const absolute = path.isAbsolute(raw) ? raw : path.resolve(cwd, raw);
+    try {
+        return fs.realpathSync(absolute);
+    }
+    catch {
+        return path.resolve(absolute);
+    }
+}
+function identityFor(input) {
+    const remoteIdentity = input.remoteUrl
+        ? `remote:${normalizeCartographerGitRemote(input.remoteUrl)}`
+        : null;
+    const repositoryBasis = remoteIdentity ??
+        (input.commonGitDir ? `common-git-dir:${input.commonGitDir}` : null);
+    const repositoryId = repositoryBasis ? digest(repositoryBasis) : null;
+    const rootBasis = repositoryId
+        ? `${input.candidate.kind}\0${repositoryId}\0${input.canonicalPath}`
+        : `${input.candidate.kind}\0structural\0${provenanceKey(input.candidate.provenance)}\0${input.canonicalPath}`;
+    const rootId = digest(rootBasis);
+    return {
+        rootId,
+        repositoryId,
+        kind: input.candidate.kind,
+        canonicalPath: input.canonicalPath,
+        gitTopLevel: input.gitTopLevel,
+        remoteUrl: input.remoteUrl,
+        revision: input.revision,
+        stateNamespace: `root-${rootId}`,
+    };
+}
+function refused(candidate, reason, identity = null) {
+    return {
+        candidate,
+        trust: 'refused',
+        reason,
+        identity,
+        structuralPopulationAllowed: false,
+        paidAuthoringAllowed: false,
+    };
+}
+function structuralOnly(candidate, reason, identity) {
+    return {
+        candidate,
+        trust: 'structural-only',
+        reason,
+        identity,
+        structuralPopulationAllowed: true,
+        paidAuthoringAllowed: false,
+    };
+}
+export class CartographerRootAuthority {
+    recordDecision;
+    now;
+    constructor(options) {
+        this.recordDecision = options.recordDecision;
+        this.now = options.now ?? (() => new Date());
+    }
+    decide(assessment, operation, signals, rule = assessment.reason) {
+        // Do not return an authority outcome if its required audit sink fails. That
+        // keeps the future live consumer from silently acting on an unlogged trust
+        // decision and makes recorder availability part of the authority contract.
+        this.recordDecision({
+            schemaVersion: 1,
+            decidedAt: this.now().toISOString(),
+            operation,
+            context: {
+                candidate: {
+                    ...assessment.candidate,
+                    provenance: { ...assessment.candidate.provenance },
+                },
+            },
+            signals: { ...signals, observedRemotes: [...signals.observedRemotes] },
+            rule,
+            outcome: {
+                trust: assessment.trust,
+                structuralPopulationAllowed: assessment.structuralPopulationAllowed,
+                paidAuthoringAllowed: assessment.paidAuthoringAllowed,
+                rootId: assessment.identity?.rootId ?? null,
+                stateNamespace: assessment.identity?.stateNamespace ?? null,
+            },
+        });
+        return assessment;
+    }
+    evaluate(candidate, operation, expectedRootId) {
+        const signals = {
+            pathState: 'unreadable',
+            canonicalPath: null,
+            gitTopLevel: null,
+            expectedRemote: candidate.expectedRemote
+                ? normalizeCartographerGitRemote(candidate.expectedRemote)
+                : null,
+            observedRemotes: [],
+            expectedRevision: candidate.expectedRevision ?? null,
+            observedRevision: null,
+        };
+        let stat;
+        try {
+            stat = fs.statSync(candidate.requestedPath);
+        }
+        catch {
+            return this.decide(refused(candidate, 'path-missing'), operation, signals);
+        }
+        signals.pathState = stat.isDirectory() ? 'directory' : 'file';
+        if (!stat.isDirectory()) {
+            return this.decide(refused(candidate, 'path-not-directory'), operation, signals);
+        }
+        let canonicalPath;
+        try {
+            canonicalPath = fs.realpathSync(candidate.requestedPath);
+        }
+        catch {
+            return this.decide(refused(candidate, 'canonicalize-failed'), operation, signals);
+        }
+        signals.canonicalPath = canonicalPath;
+        const rawTopLevel = readGit(canonicalPath, [
+            'rev-parse',
+            '--show-toplevel',
+        ]);
+        if (!rawTopLevel) {
+            return this.decide(structuralOnly(candidate, 'git-root-unreadable', identityFor({
+                candidate,
+                canonicalPath,
+                gitTopLevel: null,
+                remoteUrl: null,
+                commonGitDir: null,
+                revision: null,
+            })), operation, signals);
+        }
+        let gitTopLevel;
+        try {
+            gitTopLevel = fs.realpathSync(rawTopLevel);
+        }
+        catch {
+            return this.decide(structuralOnly(candidate, 'git-root-unreadable', identityFor({
+                candidate,
+                canonicalPath,
+                gitTopLevel: null,
+                remoteUrl: null,
+                commonGitDir: null,
+                revision: null,
+            })), operation, signals);
+        }
+        signals.gitTopLevel = gitTopLevel;
+        if (gitTopLevel !== canonicalPath) {
+            return this.decide(refused(candidate, 'candidate-not-git-root', identityFor({
+                candidate,
+                canonicalPath,
+                gitTopLevel,
+                remoteUrl: null,
+                commonGitDir: canonicalCommonGitDir(gitTopLevel),
+                revision: null,
+            })), operation, signals);
+        }
+        const remotes = readRemotes(canonicalPath);
+        signals.observedRemotes = remotes.map((remote) => remote.normalized);
+        const expectedRemote = signals.expectedRemote;
+        const matchedRemote = expectedRemote
+            ? (remotes.find((remote) => remote.normalized === expectedRemote) ?? null)
+            : (remotes.find((remote) => remote.name === 'origin') ??
+                remotes[0] ??
+                null);
+        const commonGitDir = canonicalCommonGitDir(canonicalPath);
+        const revision = readGit(canonicalPath, ['rev-parse', 'HEAD']);
+        signals.observedRevision = revision;
+        const provisionalIdentity = identityFor({
+            candidate,
+            canonicalPath,
+            gitTopLevel,
+            remoteUrl: matchedRemote?.url ?? null,
+            commonGitDir,
+            revision,
+        });
+        if (candidate.kind === 'instar-source-checkout' && !expectedRemote) {
+            return this.decide(structuralOnly(candidate, 'instar-source-expectation-missing', provisionalIdentity), operation, signals);
+        }
+        if (expectedRemote && remotes.length === 0) {
+            return this.decide(structuralOnly(candidate, 'remote-unreadable', provisionalIdentity), operation, signals);
+        }
+        if (expectedRemote && !matchedRemote) {
+            const actualIdentity = identityFor({
+                candidate,
+                canonicalPath,
+                gitTopLevel,
+                remoteUrl: remotes.find((remote) => remote.name === 'origin')?.url ??
+                    remotes[0]?.url ??
+                    null,
+                commonGitDir,
+                revision,
+            });
+            return this.decide(refused(candidate, 'remote-mismatch', actualIdentity), operation, signals);
+        }
+        if (!revision) {
+            return this.decide(structuralOnly(candidate, 'head-unreadable', provisionalIdentity), operation, signals);
+        }
+        if (candidate.expectedRevision && revision !== candidate.expectedRevision) {
+            return this.decide(refused(candidate, 'revision-mismatch', provisionalIdentity), operation, signals);
+        }
+        if (expectedRootId && provisionalIdentity.rootId !== expectedRootId) {
+            return this.decide(refused(candidate, 'root-identity-mismatch', provisionalIdentity), operation, signals);
+        }
+        return this.decide({
+            candidate,
+            trust: 'verified',
+            reason: 'verified',
+            identity: provisionalIdentity,
+            structuralPopulationAllowed: true,
+            // Agent home is an identity/state container, not an active project. Even
+            // when it is itself a valid Git repository, selecting it explicitly must
+            // not authorize the noisy-home paid sweep that exposed this failure.
+            paidAuthoringAllowed: candidate.kind !== 'agent-home',
+        }, operation, signals);
+    }
+    assess(candidate) {
+        return this.evaluate(candidate, 'assess');
+    }
+    /** Revalidate the same root identity and exact revision before a trusted operation. */
+    revalidate(assessment) {
+        if (assessment.trust !== 'verified' || !assessment.identity?.revision) {
+            return this.decide(assessment, 'revalidate', {
+                pathState: assessment.identity ? 'directory' : 'unreadable',
+                canonicalPath: assessment.identity?.canonicalPath ?? null,
+                gitTopLevel: assessment.identity?.gitTopLevel ?? null,
+                expectedRemote: assessment.candidate.expectedRemote
+                    ? normalizeCartographerGitRemote(assessment.candidate.expectedRemote)
+                    : null,
+                observedRemotes: assessment.identity?.remoteUrl
+                    ? [normalizeCartographerGitRemote(assessment.identity.remoteUrl)]
+                    : [],
+                expectedRevision: assessment.identity?.revision ?? null,
+                observedRevision: assessment.identity?.revision ?? null,
+            }, 'revalidation-not-applicable');
+        }
+        return this.evaluate({
+            ...assessment.candidate,
+            expectedRevision: assessment.identity.revision,
+        }, 'revalidate', assessment.identity.rootId);
+    }
+}
+//# sourceMappingURL=CartographerRootAuthority.js.map

package/dist/core/CartographerRootAuthority.js.map

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

package/dist/core/CartographerRootRegistry.d.ts

@@ -0,0 +1,100 @@
+import { CartographerTree } from './CartographerTree.js';
+import { type CartographerRootAssessment, type CartographerRootProvenance } from './CartographerRootAuthority.js';
+import { type CartographerPopulationConfig, type CartographerPopulationResult, type CartographerPopulationDeps } from './cartographerPopulation.js';
+import type { TopicProjectBinding } from './ScopeVerifier.js';
+import type { AgentType } from './types.js';
+export interface CartographerRootReport {
+    rootId: string;
+    repositoryId: string | null;
+    kind: 'agent-home' | 'active-project-checkout' | 'instar-source-checkout';
+    canonicalPath: string;
+    revision: string | null;
+    provenance: CartographerRootProvenance;
+    verificationState: 'verified' | 'structural-only';
+    verificationReason: CartographerRootAssessment['reason'];
+    structuralPopulationAllowed: boolean;
+    paidAuthoringAllowed: boolean;
+}
+export interface CartographerResolvedRoot {
+    tree: CartographerTree;
+    assessment: CartographerRootAssessment;
+    report: CartographerRootReport;
+}
+export type CartographerRootResolution = {
+    ok: true;
+    root: CartographerResolvedRoot;
+} | {
+    ok: false;
+    reason: string;
+    message: string;
+    report?: Omit<CartographerRootReport, 'verificationState'> & {
+        verificationState: 'refused';
+    };
+};
+export type CartographerAuthoringDecision = {
+    ok: true;
+    root: CartographerResolvedRoot;
+} | {
+    ok: false;
+    reason: string;
+    message: string;
+};
+export interface CartographerBootPopulationResult extends CartographerPopulationResult {
+    rootAuthority: CartographerRootReport;
+}
+export interface CartographerRootRegistryOptions {
+    agentType: AgentType;
+    agentHome: string;
+    agentName: string;
+    stateDir: string;
+    serverProject?: {
+        projectDir: string;
+        projectName: string;
+        gitRemote?: string;
+    };
+    topicBindings: () => Record<string, TopicProjectBinding>;
+    population?: {
+        config?: CartographerPopulationConfig;
+        onYield?: CartographerPopulationDeps['onYield'];
+        /** Test seam only. Production always omits this and uses the real worker. */
+        runDetectWorker?: CartographerPopulationDeps['runDetectWorker'];
+    };
+    decisionLogPath?: string;
+    /** Active decision-log ceiling. Default 5 MiB. */
+    decisionLogMaxBytes?: number;
+    /** Rotated archives retained. Default 2. */
+    decisionLogKeepArchives?: number;
+    now?: () => Date;
+    log?: (message: string) => void;
+}
+/**
+ * Registry lifetime is one server boot. Assessments therefore pin the exact
+ * revision that produced the current hierarchy; paid writes revalidate against
+ * that pin instead of silently adopting a later HEAD.
+ */
+export declare class CartographerRootRegistry {
+    private readonly options;
+    private readonly authority;
+    private readonly decisionLogPath;
+    private readonly decisionLogMaxBytes;
+    private readonly decisionLogKeepArchives;
+    private readonly now;
+    private readonly log;
+    private readonly cachedBySelection;
+    private readonly treesByRootId;
+    constructor(options: CartographerRootRegistryOptions);
+    private recordDecision;
+    private select;
+    private selectionSignature;
+    resolve(topicId?: number): CartographerRootResolution;
+    authorizePaidAuthoring(root: CartographerResolvedRoot): CartographerAuthoringDecision;
+    /**
+     * Per-root trees are regenerable caches, not history. At boot, remove only
+     * authority-shaped namespaces no longer selected by any live binding so old
+     * topic churn cannot accumulate an unbounded archive of project maps.
+     */
+    private pruneInactiveRootCaches;
+    /** Enumerate all explicit live roots and rebuild each hierarchy once per boot. */
+    populateOnBoot(): Promise<CartographerBootPopulationResult[]>;
+}
+//# sourceMappingURL=CartographerRootRegistry.d.ts.map

package/dist/core/CartographerRootRegistry.d.ts.map

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