@amityco/social-plus-vise 0.4.0

package/dist/tools/compliance.js

@@ -0,0 +1,965 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { classifyOutcome } from "../outcomes.js";
+import { objectInput, optionalStringField, stringField, textResult } from "../types.js";
+import { packageVersion } from "../version.js";
+import { inspectProject, validateSetup } from "./project.js";
+const complianceDirName = "sp-vise";
+const attestationsDirName = "attestations";
+const schemaVersion = 1;
+const confidenceRank = { low: 0, medium: 1, high: 2 };
+export const initComplianceTool = {
+    name: "init_compliance",
+    description: "Initialize the local sp-vise compliance sidecar for a customer integration request.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            repoPath: { type: "string" },
+            request: { type: "string" },
+            surfacePath: { type: "string" },
+        },
+        required: ["repoPath", "request"],
+        additionalProperties: false,
+    },
+    async call(input) {
+        const args = objectInput(input);
+        return textResult(await initCompliance(stringField(args, "repoPath"), stringField(args, "request"), optionalStringField(args, "surfacePath")));
+    },
+};
+export const checkComplianceTool = {
+    name: "check_compliance",
+    description: "Check compliance rules against the current source and recorded attestations. Read-only.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            repoPath: { type: "string" },
+        },
+        required: ["repoPath"],
+        additionalProperties: false,
+    },
+    async call(input) {
+        const args = objectInput(input);
+        return textResult(await checkCompliance(stringField(args, "repoPath")));
+    },
+};
+export const syncComplianceTool = {
+    name: "sync_compliance",
+    description: "Persist current deterministic-pass compliance results into the sp-vise sidecar.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            repoPath: { type: "string" },
+        },
+        required: ["repoPath"],
+        additionalProperties: false,
+    },
+    async call(input) {
+        const args = objectInput(input);
+        return textResult(await syncCompliance(stringField(args, "repoPath")));
+    },
+};
+export const attestRuleTool = {
+    name: "attest_rule",
+    description: "Record a host-agent or local-human attestation for one compliance rule.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            repoPath: { type: "string" },
+            ruleId: { type: "string" },
+            confidence: { type: "string" },
+            signer: { type: "string" },
+            identity: { type: "string" },
+            rationale: { type: "string" },
+            evidence: { type: "object", additionalProperties: true },
+        },
+        required: ["repoPath", "ruleId", "confidence", "signer", "rationale", "evidence"],
+        additionalProperties: false,
+    },
+    async call(input) {
+        const args = objectInput(input);
+        return textResult(await attestRule({
+            repoPath: stringField(args, "repoPath"),
+            ruleId: stringField(args, "ruleId"),
+            confidence: confidenceField(args.confidence),
+            signer: signerField(args.signer),
+            identity: optionalStringField(args, "identity"),
+            rationale: stringField(args, "rationale"),
+            evidence: evidenceField(args.evidence),
+        }));
+    },
+};
+export const explainRuleTool = {
+    name: "explain_rule",
+    description: "Explain one compliance rule, including rationale, enforcement, and evidence schema.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            ruleId: { type: "string" },
+        },
+        required: ["ruleId"],
+        additionalProperties: false,
+    },
+    async call(input) {
+        const args = objectInput(input);
+        return textResult(await explainRule(stringField(args, "ruleId")));
+    },
+};
+export const initEngagementTool = {
+    name: "init_engagement",
+    description: "Initialize sp-vise/engagement.json with customer, tier, and contracted outcome scope. Local-only metadata; v0.5 will route review-queue uploads using these fields.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            repoPath: { type: "string" },
+            tier: { type: "string", description: "free | pro | partner. Defaults to free." },
+            customerId: { type: "string" },
+            scope: { type: "array", items: { type: "string" }, description: "Outcomes covered by this engagement." },
+            targetCompletionDate: { type: "string", description: "Optional ISO date YYYY-MM-DD." },
+            reviewerName: { type: "string" },
+            reviewerEmail: { type: "string" },
+            evidenceUploadConsent: { type: "boolean" },
+        },
+        required: ["repoPath"],
+        additionalProperties: false,
+    },
+    async call(input) {
+        const args = objectInput(input);
+        return textResult(await initEngagement({
+            repoPath: stringField(args, "repoPath"),
+            tier: optionalStringField(args, "tier"),
+            customerId: optionalStringField(args, "customerId"),
+            scope: stringArray(args.scope),
+            targetCompletionDate: optionalStringField(args, "targetCompletionDate"),
+            reviewerName: optionalStringField(args, "reviewerName"),
+            reviewerEmail: optionalStringField(args, "reviewerEmail"),
+            evidenceUploadConsent: args.evidenceUploadConsent === true,
+        }));
+    },
+};
+export const showEngagementTool = {
+    name: "show_engagement",
+    description: "Read sp-vise/engagement.json and return the engagement metadata. Read-only.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            repoPath: { type: "string" },
+        },
+        required: ["repoPath"],
+        additionalProperties: false,
+    },
+    async call(input) {
+        const args = objectInput(input);
+        return textResult(await showEngagement(stringField(args, "repoPath")));
+    },
+};
+function stringArray(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    return value.filter((item) => typeof item === "string" && item.trim() !== "");
+}
+const validTiers = new Set(["free", "pro", "partner"]);
+const validOutcomes = new Set(["setup-sdk", "setup-push", "setup-live-data", "add-feed", "troubleshoot", "validate-setup", "unknown"]);
+export async function initEngagement(args) {
+    const repoRoot = path.resolve(args.repoPath);
+    const engagementFile = engagementPath(repoRoot);
+    if (await readJsonIfExists(engagementFile)) {
+        throw new Error(`Engagement file already exists at ${engagementFile}. Edit it directly to extend scope, or remove it first to re-init.`);
+    }
+    const tier = (args.tier ?? "free");
+    if (!validTiers.has(tier)) {
+        throw new Error(`Unknown tier: ${args.tier}. Expected one of: ${Array.from(validTiers).join(", ")}.`);
+    }
+    const requestedOutcomes = (args.scope ?? []).map((outcome) => outcome.trim()).filter(Boolean);
+    for (const outcome of requestedOutcomes) {
+        if (!validOutcomes.has(outcome)) {
+            throw new Error(`Unknown outcome in scope: ${outcome}. Expected one of: ${Array.from(validOutcomes).join(", ")}.`);
+        }
+    }
+    if (args.targetCompletionDate && !/^\d{4}-\d{2}-\d{2}$/.test(args.targetCompletionDate)) {
+        throw new Error(`target-completion must be YYYY-MM-DD; got "${args.targetCompletionDate}".`);
+    }
+    const reviewerAssignment = args.reviewerName || args.reviewerEmail
+        ? { name: args.reviewerName, email: args.reviewerEmail }
+        : undefined;
+    const engagement = {
+        schema_version: schemaVersion,
+        foundry_version: packageVersion,
+        engagement_id: randomUUID(),
+        customer_id: args.customerId,
+        tier,
+        scope: { outcomes: requestedOutcomes },
+        target_completion_date: args.targetCompletionDate,
+        reviewer_assignment: reviewerAssignment,
+        evidence_upload_consent: args.evidenceUploadConsent === true,
+        generated_at: new Date().toISOString(),
+    };
+    await mkdir(sidecarDir(repoRoot), { recursive: true });
+    await writeJson(engagementFile, engagement);
+    return {
+        status: "initialized",
+        engagement_id: engagement.engagement_id,
+        tier: engagement.tier,
+        scope: engagement.scope,
+        customer_id: engagement.customer_id,
+        file: engagementFile,
+        note: "Engagement metadata is local-only in v0.4.x. v0.5 review queue will route uploads using these fields.",
+    };
+}
+export async function showEngagement(repoPath) {
+    const repoRoot = path.resolve(repoPath);
+    const engagement = await readEngagement(repoRoot);
+    if (!engagement) {
+        return { status: "absent", note: "No engagement.json found. Run `vise engagement init` to create one." };
+    }
+    return { status: "present", ...engagement };
+}
+async function readEngagement(repoRoot) {
+    return readJsonIfExists(engagementPath(repoRoot));
+}
+function engagementPath(repoRoot) {
+    return path.join(sidecarDir(repoRoot), "engagement.json");
+}
+export async function initCompliance(repoPath, request, surfacePath) {
+    const repoRoot = path.resolve(repoPath);
+    const inspection = await inspectProject(repoRoot, surfacePath);
+    const outcome = classifyOutcome(request);
+    const rules = await applicableRules(outcome, inspection.platforms);
+    const refs = rules.map(ruleRef);
+    const engagement = await readEngagement(repoRoot);
+    const compliance = {
+        schema_version: schemaVersion,
+        foundry_version: packageVersion,
+        ruleset_digest: digestJson(refs),
+        generated_at: new Date().toISOString(),
+        last_synced_at: null,
+        outcome,
+        engagement_id: engagement?.engagement_id,
+        surface: inspection.selectedSurface ? { path: inspection.selectedSurface.path, platforms: inspection.selectedSurface.platforms } : undefined,
+        rules: refs,
+    };
+    await mkdir(attestationsDir(repoRoot), { recursive: true });
+    await writeJson(compliancePath(repoRoot), compliance);
+    await writeJson(path.join(sidecarDir(repoRoot), "inspection.json"), inspection);
+    await writeFile(path.join(sidecarDir(repoRoot), "README.md"), sidecarReadme(compliance), "utf8");
+    const warnings = [];
+    if (engagement && engagement.scope.outcomes.length > 0 && !engagement.scope.outcomes.includes(outcome)) {
+        warnings.push(`Outcome "${outcome}" is not in the engagement scope (${engagement.scope.outcomes.join(", ")}). Compliance was still initialized; extend the scope in engagement.json or re-run vise engagement init.`);
+    }
+    return {
+        status: "initialized",
+        sidecar: complianceDirName,
+        outcome,
+        surfacePath: inspection.selectedSurface?.path,
+        rules: refs.length,
+        engagement_id: engagement?.engagement_id,
+        ...(warnings.length > 0 && { warnings }),
+        nextStep: "Run vise check, then implement until rules pass deterministically or are attested.",
+    };
+}
+export async function applicableComplianceRuleSummaries(outcome, platforms) {
+    return (await applicableRules(outcome, platforms)).map(ruleRef);
+}
+export async function checkCompliance(repoPath) {
+    const repoRoot = path.resolve(repoPath);
+    const compliance = await readCompliance(repoRoot);
+    const rules = await rulesById();
+    const drift = contractDrift(compliance, rules);
+    if (drift.length > 0) {
+        return {
+            status: "contract-drift",
+            exitCode: 4,
+            outcome: compliance.outcome,
+            surfacePath: compliance.surface?.path,
+            summary: { "contract-drift": drift.length },
+            rules: drift,
+        };
+    }
+    const inspection = await inspectProject(repoRoot, compliance.surface?.path === "." ? undefined : compliance.surface?.path);
+    const platform = inspection.platforms[0] ?? "unknown";
+    const findings = await validateSetup(inspection.effectiveRoot, platform);
+    const findingsById = new Map(findings.map((finding) => [finding.ruleId, finding]));
+    const attestations = await readAttestations(repoRoot);
+    const results = [];
+    for (const ref of compliance.rules) {
+        const rule = rules.get(ref.rule_id);
+        if (!rule) {
+            results.push({ ruleId: ref.rule_id, title: ref.rule_id, severity: ref.severity, status: "stale", reason: "Rule is missing from installed Vise." });
+            continue;
+        }
+        // Blockers run first. If any external prerequisite is missing, the rule is
+        // "blocked" — the host agent cannot fix this alone, so we surface it and
+        // stop evaluating this rule. Customer-readable reasons are attached so the
+        // user knows what to provide.
+        const blockersFired = await runBlockers(rule, inspection.effectiveRoot);
+        if (blockersFired.length > 0) {
+            results.push({
+                ruleId: rule.id,
+                title: rule.title,
+                severity: rule.severity,
+                status: "blocked",
+                reason: blockersFired.map((blocker) => blocker.reason).join(" "),
+                blockers_fired: blockersFired,
+                current_rule: ruleSummary(rule),
+            });
+            continue;
+        }
+        const finding = deterministicFinding(rule, findingsById);
+        if (!finding) {
+            results.push({
+                ruleId: rule.id,
+                title: rule.title,
+                severity: rule.severity,
+                status: "deterministic-pass",
+                evidence: { source: "validate_setup", finding_absent: deterministicFindingIds(rule) },
+            });
+            continue;
+        }
+        const attestation = attestations.get(rule.id);
+        if (attestation) {
+            // Deterministic-pass records are historical sync evidence, not waivers.
+            // If the current source now produces a finding, the old sync record must
+            // not mask code drift; the next `vise sync` will remove it.
+            if (attestation.status === "deterministic-pass") {
+                results.push({
+                    ruleId: rule.id,
+                    title: rule.title,
+                    severity: rule.severity,
+                    status: rule.enforcement.attestation.allowed ? "attestation-needed" : "deterministic-fail",
+                    reason: rule.enforcement.attestation.allowed
+                        ? "Current deterministic check failed; previously synced deterministic-pass evidence is stale."
+                        : "Current deterministic check failed; this rule does not allow attestation.",
+                    finding,
+                    recommendation: finding.recommendation,
+                    current_rule: ruleSummary(rule),
+                });
+                continue;
+            }
+            const exactMatch = attestation.rule_digest === ref.rule_digest && attestation.ruleset_digest === compliance.ruleset_digest;
+            const grandfathered = !exactMatch && isAttestationGrandfathered(rule, attestation);
+            if (exactMatch || grandfathered) {
+                const sourceFingerprintStatus = await checkSourceFingerprints(repoRoot, inspection.effectiveRoot, attestation.source_fingerprints ?? []);
+                const staleFingerprints = sourceFingerprintStatus.filter((item) => item.status !== "match");
+                if (staleFingerprints.length > 0) {
+                    results.push({
+                        ruleId: rule.id,
+                        title: rule.title,
+                        severity: rule.severity,
+                        status: rule.enforcement.attestation.allowed ? "attestation-needed" : "deterministic-fail",
+                        reason: "Recorded attestation source fingerprints changed. Re-check the evidence and record a fresh attestation.",
+                        finding,
+                        recommendation: finding.recommendation,
+                        current_rule: ruleSummary(rule),
+                        source_fingerprint_status: sourceFingerprintStatus,
+                    });
+                    continue;
+                }
+                const deprecated = grandfathered && (rule.deprecated_versions ?? []).includes(attestation.rule_version);
+                results.push({
+                    ruleId: rule.id,
+                    title: rule.title,
+                    severity: rule.severity,
+                    status: "attested",
+                    reason: grandfathered
+                        ? `Grandfathered ${attestation.signer_claim.kind} attestation from rule v${attestation.rule_version} (current is v${rule.version}; compatible_with allows it).`
+                        : `Recorded ${attestation.signer_claim.kind} attestation.`,
+                    attestation: attestationPathFor(rule.id),
+                    evidence: attestation.evidence,
+                    ...(sourceFingerprintStatus.length > 0 && { source_fingerprint_status: sourceFingerprintStatus }),
+                    ...(deprecated && {
+                        deprecation_warning: `Rule v${attestation.rule_version} is marked deprecated in the current Vise. Re-attest against v${rule.version} before a future version removes v${attestation.rule_version} from compatible_with.`,
+                    }),
+                });
+                continue;
+            }
+        }
+        results.push({
+            ruleId: rule.id,
+            title: rule.title,
+            severity: rule.severity,
+            status: rule.enforcement.attestation.allowed ? "attestation-needed" : "deterministic-fail",
+            reason: rule.enforcement.attestation.allowed ? "Deterministic check failed and no valid attestation exists." : "This rule does not allow attestation.",
+            finding,
+            recommendation: finding.recommendation,
+            current_rule: ruleSummary(rule),
+        });
+    }
+    const summary = summarize(results);
+    const hasBlocked = results.some((result) => result.status === "blocked");
+    const hasDeterministicFailure = results.some((result) => result.status === "deterministic-fail");
+    const needsAttestation = results.some((result) => result.status === "attestation-needed" || result.status === "stale");
+    // Precedence: blocked (exit 3) > deterministic-failures (2) > needs-attestation (1) > green (0).
+    // Contract drift (exit 4) is handled earlier and short-circuits the loop.
+    // Blocked wins because the agent cannot proceed without customer input;
+    // surfacing a smaller failure first would distract from the real blocker.
+    return {
+        status: hasBlocked
+            ? "blocked"
+            : hasDeterministicFailure
+                ? "deterministic-failures"
+                : needsAttestation
+                    ? "needs-attestation"
+                    : "green",
+        exitCode: hasBlocked ? 3 : hasDeterministicFailure ? 2 : needsAttestation ? 1 : 0,
+        outcome: compliance.outcome,
+        surfacePath: compliance.surface?.path,
+        summary,
+        rules: results,
+    };
+}
+export async function syncCompliance(repoPath) {
+    const repoRoot = path.resolve(repoPath);
+    const compliance = await readCompliance(repoRoot);
+    const check = await checkCompliance(repoRoot);
+    const written = [];
+    const removed = [];
+    await mkdir(attestationsDir(repoRoot), { recursive: true });
+    for (const result of check.rules) {
+        const filePath = path.join(attestationsDir(repoRoot), attestationPathFor(result.ruleId));
+        if (result.status === "deterministic-pass") {
+            const rule = (await rulesById()).get(result.ruleId);
+            if (!rule) {
+                continue;
+            }
+            const existing = await readJsonIfExists(filePath);
+            if (existing?.status === "attested") {
+                continue;
+            }
+            const attestation = buildAttestation(compliance, rule, "spf-deterministic", "high", undefined, "Deterministic check passed.", result.evidence ?? {});
+            await writeJson(filePath, attestation);
+            written.push(filePath);
+        }
+        else if (result.status === "deterministic-fail" || result.status === "attestation-needed") {
+            const existing = await readJsonIfExists(filePath);
+            if (existing?.status === "deterministic-pass") {
+                await rm(filePath, { force: true });
+                removed.push(filePath);
+            }
+        }
+    }
+    compliance.last_synced_at = new Date().toISOString();
+    await writeJson(compliancePath(repoRoot), compliance);
+    return {
+        status: "synced",
+        written,
+        removed,
+        last_synced_at: compliance.last_synced_at,
+    };
+}
+export async function attestRule(args) {
+    const repoRoot = path.resolve(args.repoPath);
+    const compliance = await readCompliance(repoRoot);
+    const rules = await rulesById();
+    const rule = rules.get(args.ruleId);
+    if (!rule || !compliance.rules.some((ref) => ref.rule_id === args.ruleId)) {
+        throw new Error(`Rule is not applicable in this compliance contract: ${args.ruleId}`);
+    }
+    if (!rule.enforcement.attestation.allowed) {
+        throw new Error(`Rule does not allow attestation: ${args.ruleId}`);
+    }
+    if (args.signer === "host-agent" && confidenceRank[args.confidence] < confidenceRank[rule.enforcement.attestation.host_agent_min_confidence ?? "high"]) {
+        throw new Error(`Host-agent confidence ${args.confidence} is below ${rule.enforcement.attestation.host_agent_min_confidence ?? "high"} for ${args.ruleId}. Use --signer human if a local human accepts responsibility.`);
+    }
+    if (args.signer === "human" && rule.enforcement.attestation.human_allowed === false) {
+        throw new Error(`Rule does not allow local human attestations: ${args.ruleId}`);
+    }
+    validateEvidence(rule, args.evidence);
+    await mkdir(attestationsDir(repoRoot), { recursive: true });
+    const sourceFingerprints = await collectSourceFingerprints(repoRoot, sourceRootForCompliance(repoRoot, compliance), args.evidence);
+    const attestation = buildAttestation(compliance, rule, args.signer, args.confidence, args.identity, args.rationale, args.evidence, sourceFingerprints);
+    const filePath = path.join(attestationsDir(repoRoot), attestationPathFor(args.ruleId));
+    await writeJson(filePath, attestation);
+    return {
+        status: "attested",
+        ruleId: args.ruleId,
+        destination: filePath,
+        signer_claim: attestation.signer_claim,
+        source_fingerprints: sourceFingerprints,
+    };
+}
+export async function explainRule(ruleId) {
+    const rules = await rulesById();
+    const rule = rules.get(ruleId);
+    if (!rule) {
+        throw new Error(`Unknown compliance rule: ${ruleId}`);
+    }
+    return {
+        id: rule.id,
+        version: rule.version,
+        title: rule.title,
+        severity: rule.severity,
+        rationale: rule.rationale,
+        applies_when: rule.applies_when,
+        compatible_with: rule.compatible_with,
+        deterministic: rule.enforcement.deterministic ?? [],
+        attestation: rule.enforcement.attestation,
+        summary: ruleSummary(rule),
+        rule_digest: digestRule(rule),
+    };
+}
+export async function statusCompliance(repoPath) {
+    const repoRoot = path.resolve(repoPath);
+    const check = await checkCompliance(repoPath);
+    const engagement = await readEngagement(repoRoot);
+    return {
+        status: check.status,
+        exitCode: check.exitCode,
+        outcome: check.outcome,
+        surfacePath: check.surfacePath,
+        summary: check.summary,
+        ...(engagement && {
+            engagement: {
+                engagement_id: engagement.engagement_id,
+                tier: engagement.tier,
+                customer_id: engagement.customer_id,
+                scope: engagement.scope,
+                outcome_in_scope: engagement.scope.outcomes.length === 0 || engagement.scope.outcomes.includes(check.outcome),
+                target_completion_date: engagement.target_completion_date,
+                reviewer_assignment: engagement.reviewer_assignment,
+            },
+        }),
+    };
+}
+async function applicableRules(outcome, platforms) {
+    const files = await loadRuleFiles();
+    return files
+        .flatMap((file) => file.rules)
+        .filter((rule) => {
+        const outcomeMatch = !rule.applies_when.outcomes || rule.applies_when.outcomes.includes(outcome);
+        const platformMatch = !rule.applies_when.platforms || rule.applies_when.platforms.some((platform) => platforms.includes(platform));
+        return outcomeMatch && platformMatch;
+    });
+}
+async function loadRuleFiles() {
+    const dir = rulesDir();
+    const entries = await readdir(dir);
+    const files = entries.filter((entry) => entry.endsWith(".yaml")).sort();
+    const loaded = [];
+    for (const file of files) {
+        loaded.push(JSON.parse(await readFile(path.join(dir, file), "utf8")));
+    }
+    return loaded;
+}
+async function rulesById() {
+    const rules = (await loadRuleFiles()).flatMap((file) => file.rules);
+    return new Map(rules.map((rule) => [rule.id, rule]));
+}
+function ruleRef(rule) {
+    return {
+        rule_id: rule.id,
+        rule_version: rule.version,
+        rule_digest: digestRule(rule),
+        severity: rule.severity,
+    };
+}
+function contractDrift(compliance, rules) {
+    const results = [];
+    const refs = compliance.rules.map((ref) => {
+        const rule = rules.get(ref.rule_id);
+        return rule ? ruleRef(rule) : ref;
+    });
+    const installedRulesetDigest = digestJson(refs);
+    if (installedRulesetDigest !== compliance.ruleset_digest) {
+        results.push({
+            ruleId: "contract.ruleset",
+            title: "Compliance contract ruleset changed",
+            severity: "error",
+            status: "stale",
+            reason: "Installed Vise ruleset differs from sp-vise/compliance.json. Re-run vise init to accept the new contract.",
+        });
+    }
+    for (const ref of compliance.rules) {
+        const rule = rules.get(ref.rule_id);
+        if (!rule) {
+            results.push({ ruleId: ref.rule_id, title: ref.rule_id, severity: ref.severity, status: "stale", reason: "Rule is missing from installed Vise." });
+            continue;
+        }
+        const digest = digestRule(rule);
+        if (digest !== ref.rule_digest) {
+            const grandfatherCovers = (rule.compatible_with ?? []).includes(ref.rule_version);
+            const reason = grandfatherCovers
+                ? `Rule digest changed since vise init (v${ref.rule_version} → v${rule.version}; new version is backwards-compatible — re-run vise init; existing attestations will be grandfathered).`
+                : `Rule digest changed since vise init (v${ref.rule_version} → v${rule.version}).`;
+            results.push({
+                ruleId: ref.rule_id,
+                title: rule.title,
+                severity: ref.severity,
+                status: "stale",
+                reason,
+                current_rule: ruleSummary(rule),
+            });
+        }
+    }
+    return results;
+}
+function deterministicFinding(rule, findingsById) {
+    for (const id of deterministicFindingIds(rule)) {
+        const finding = findingsById.get(id);
+        if (finding) {
+            return finding;
+        }
+    }
+    return undefined;
+}
+function deterministicFindingIds(rule) {
+    return (rule.enforcement.deterministic ?? [])
+        .filter((check) => check.check === "validator-finding-absent")
+        .map((check) => check.finding_rule_id);
+}
+function buildAttestation(compliance, rule, signer, confidence, identity, rationale, evidence, sourceFingerprints = []) {
+    const ref = compliance.rules.find((item) => item.rule_id === rule.id);
+    if (!ref) {
+        throw new Error(`Rule is not in compliance contract: ${rule.id}`);
+    }
+    const withoutHash = {
+        rule_id: rule.id,
+        rule_version: rule.version,
+        rule_digest: ref.rule_digest,
+        ruleset_digest: compliance.ruleset_digest,
+        foundry_version: packageVersion,
+        status: signer === "spf-deterministic" ? "deterministic-pass" : "attested",
+        signer_claim: {
+            kind: signer,
+            identity: identity ?? (signer === "spf-deterministic" ? "spf" : signer),
+            tool_version: signer === "host-agent" ? "unknown" : undefined,
+            confidence,
+        },
+        signature: null,
+        evidence,
+        source_fingerprints: sourceFingerprints,
+        rationale_for_attestation: rationale,
+        attested_at: new Date().toISOString(),
+    };
+    return {
+        ...withoutHash,
+        payload_hash: digestJson(withoutHash),
+    };
+}
+function sourceRootForCompliance(repoRoot, compliance) {
+    if (!compliance.surface?.path || compliance.surface.path === ".") {
+        return repoRoot;
+    }
+    return path.resolve(repoRoot, compliance.surface.path);
+}
+async function collectSourceFingerprints(repoRoot, sourceRoot, evidence) {
+    const capturedAt = new Date().toISOString();
+    const fingerprints = [];
+    const seen = new Set();
+    for (const item of evidenceSourcePathCandidates(evidence)) {
+        const resolved = await resolveEvidenceSourcePath(repoRoot, sourceRoot, item.candidate);
+        if (!resolved || seen.has(resolved.relativePath)) {
+            continue;
+        }
+        seen.add(resolved.relativePath);
+        const fileStat = await stat(resolved.absolutePath);
+        fingerprints.push({
+            evidence_field: item.evidenceField,
+            path: resolved.relativePath,
+            sha256: await digestFile(resolved.absolutePath),
+            size_bytes: fileStat.size,
+            captured_at: capturedAt,
+        });
+    }
+    return fingerprints;
+}
+async function checkSourceFingerprints(repoRoot, sourceRoot, fingerprints) {
+    const statuses = [];
+    for (const fingerprint of fingerprints) {
+        const resolved = await resolveEvidenceSourcePath(repoRoot, sourceRoot, fingerprint.path);
+        if (!resolved) {
+            statuses.push({
+                evidence_field: fingerprint.evidence_field,
+                path: fingerprint.path,
+                expected_sha256: fingerprint.sha256,
+                status: "missing",
+            });
+            continue;
+        }
+        const actualSha256 = await digestFile(resolved.absolutePath);
+        statuses.push({
+            evidence_field: fingerprint.evidence_field,
+            path: fingerprint.path,
+            expected_sha256: fingerprint.sha256,
+            actual_sha256: actualSha256,
+            status: actualSha256 === fingerprint.sha256 ? "match" : "changed",
+        });
+    }
+    return statuses;
+}
+function evidenceSourcePathCandidates(evidence) {
+    const candidates = [];
+    function visit(value, fieldPath) {
+        if (typeof value === "string") {
+            for (const candidate of sourcePathCandidatesFromString(value)) {
+                candidates.push({ evidenceField: fieldPath, candidate });
+            }
+            return;
+        }
+        if (Array.isArray(value)) {
+            value.forEach((item, index) => visit(item, `${fieldPath}[${index}]`));
+            return;
+        }
+        if (value && typeof value === "object") {
+            for (const [key, nestedValue] of Object.entries(value)) {
+                visit(nestedValue, fieldPath ? `${fieldPath}.${key}` : key);
+            }
+        }
+    }
+    visit(evidence, "");
+    return candidates;
+}
+function sourcePathCandidatesFromString(value) {
+    const trimmed = value.trim();
+    const candidates = new Set();
+    if (looksLikeSourcePath(trimmed)) {
+        candidates.add(trimmed);
+    }
+    const pathPattern = /(?:[A-Za-z0-9_@.-]+\/)+[A-Za-z0-9_@.-]+\.(?:ts|tsx|js|jsx|kt|java|dart|swift|xml|gradle|kts|json|ya?ml|env|plist|pbxproj|podspec)|\b(?:Podfile|Package\.swift|pubspec\.yaml|package\.json|AndroidManifest\.xml)\b/g;
+    for (const match of trimmed.matchAll(pathPattern)) {
+        candidates.add(match[0]);
+    }
+    return Array.from(candidates).map(cleanEvidencePathCandidate).filter(Boolean);
+}
+function looksLikeSourcePath(value) {
+    return (/[/\\]/.test(value) ||
+        /^(?:Podfile|Package\.swift|pubspec\.yaml|package\.json|AndroidManifest\.xml)$/.test(value) ||
+        /\.(?:ts|tsx|js|jsx|kt|java|dart|swift|xml|gradle|kts|json|ya?ml|env|plist|pbxproj|podspec)(?::\d+)?$/i.test(value));
+}
+function cleanEvidencePathCandidate(value) {
+    return value
+        .trim()
+        .replace(/^["'`]+|["'`,.;)]+$/g, "")
+        .replace(/#L\d+(?:-L\d+)?$/, "")
+        .replace(/:\d+(?::\d+)?$/, "");
+}
+async function resolveEvidenceSourcePath(repoRoot, sourceRoot, candidate) {
+    const possiblePaths = path.isAbsolute(candidate)
+        ? [path.resolve(candidate)]
+        : [path.resolve(sourceRoot, candidate), path.resolve(repoRoot, candidate)];
+    for (const possiblePath of possiblePaths) {
+        if (!pathInside(repoRoot, possiblePath)) {
+            continue;
+        }
+        try {
+            if (!(await stat(possiblePath)).isFile()) {
+                continue;
+            }
+        }
+        catch {
+            continue;
+        }
+        return {
+            absolutePath: possiblePath,
+            relativePath: path.relative(repoRoot, possiblePath).split(path.sep).join(path.posix.sep),
+        };
+    }
+    return undefined;
+}
+function pathInside(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+async function digestFile(filePath) {
+    return `sha256:${createHash("sha256").update(await readFile(filePath)).digest("hex")}`;
+}
+export function ruleSummary(rule) {
+    return {
+        version: rule.version,
+        severity: rule.severity,
+        title: rule.title,
+        compatible_with: rule.compatible_with,
+        deprecated_versions: rule.deprecated_versions,
+        blockers: (rule.enforcement.blockers ?? []).map((blocker) => ({
+            check: blocker.check,
+            path: "path" in blocker ? blocker.path : undefined,
+            pattern: "pattern" in blocker ? blocker.pattern : undefined,
+            reason: blocker.reason,
+        })),
+        deterministic_check_ids: (rule.enforcement.deterministic ?? []).map((check) => check.finding_rule_id),
+        attestation_allowed: rule.enforcement.attestation.allowed,
+        host_agent_min_confidence: rule.enforcement.attestation.host_agent_min_confidence,
+        human_allowed: rule.enforcement.attestation.human_allowed !== false,
+        evidence_field_names: (rule.enforcement.attestation.evidence_required ?? []).map((field) => field.field),
+    };
+}
+export async function runBlockers(rule, root) {
+    const fired = [];
+    for (const blocker of rule.enforcement.blockers ?? []) {
+        if (blocker.check === "file-absent") {
+            const filePath = path.resolve(root, blocker.path);
+            if (!(await fileExists(filePath))) {
+                fired.push({ check: "file-absent", path: blocker.path, reason: blocker.reason });
+            }
+        }
+        else if (blocker.check === "file-content-missing") {
+            const filePath = path.resolve(root, blocker.path);
+            let content = "";
+            try {
+                content = await readFile(filePath, "utf8");
+            }
+            catch {
+                fired.push({ check: "file-content-missing", path: blocker.path, pattern: blocker.pattern, reason: blocker.reason });
+                continue;
+            }
+            const re = new RegExp(blocker.pattern);
+            if (!re.test(content)) {
+                fired.push({ check: "file-content-missing", path: blocker.path, pattern: blocker.pattern, reason: blocker.reason });
+            }
+        }
+    }
+    return fired;
+}
+async function fileExists(filePath) {
+    try {
+        await stat(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function isAttestationGrandfathered(rule, attestation) {
+    if (attestation.rule_id !== rule.id) {
+        return false;
+    }
+    if (attestation.rule_version === rule.version) {
+        return false;
+    }
+    return (rule.compatible_with ?? []).includes(attestation.rule_version);
+}
+function validateEvidence(rule, evidence) {
+    for (const field of rule.enforcement.attestation.evidence_required ?? []) {
+        if (!(field.field in evidence)) {
+            throw new Error(`Missing required evidence field for ${rule.id}: ${field.field}`);
+        }
+    }
+}
+async function readCompliance(repoRoot) {
+    const file = compliancePath(repoRoot);
+    try {
+        return JSON.parse(await readFile(file, "utf8"));
+    }
+    catch {
+        throw new Error(`No compliance sidecar found. Run vise init first: ${file}`);
+    }
+}
+async function readAttestations(repoRoot) {
+    const dir = attestationsDir(repoRoot);
+    const result = new Map();
+    let entries = [];
+    try {
+        entries = await readdir(dir);
+    }
+    catch {
+        return result;
+    }
+    for (const entry of entries) {
+        if (!entry.endsWith(".json")) {
+            continue;
+        }
+        const attestation = await readJsonIfExists(path.join(dir, entry));
+        if (attestation?.rule_id) {
+            result.set(attestation.rule_id, attestation);
+        }
+    }
+    return result;
+}
+async function readJsonIfExists(filePath) {
+    try {
+        if (!(await stat(filePath)).isFile()) {
+            return undefined;
+        }
+        return JSON.parse(await readFile(filePath, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function writeJson(filePath, value) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+function summarize(results) {
+    const summary = {};
+    for (const result of results) {
+        summary[result.status] = (summary[result.status] ?? 0) + 1;
+    }
+    return summary;
+}
+function sidecarReadme(compliance) {
+    return [
+        "# social.plus Vise Compliance",
+        "",
+        "This directory records the local compliance contract for this integration.",
+        "",
+        `- Outcome: ${compliance.outcome}`,
+        `- Rules: ${compliance.rules.length}`,
+        `- Generated: ${compliance.generated_at}`,
+        "",
+        "Run `vise check` to verify current status and `vise sync` to persist deterministic-pass evidence.",
+        "Host-agent and human attestations include source fingerprints for cited files; `vise check` marks them stale if those files change.",
+        "",
+    ].join("\n");
+}
+function sidecarDir(repoRoot) {
+    return path.join(repoRoot, complianceDirName);
+}
+function attestationsDir(repoRoot) {
+    return path.join(sidecarDir(repoRoot), attestationsDirName);
+}
+function compliancePath(repoRoot) {
+    return path.join(sidecarDir(repoRoot), "compliance.json");
+}
+function attestationPathFor(ruleId) {
+    return `${ruleId.replace(/[^a-zA-Z0-9_.-]/g, "_")}.json`;
+}
+function rulesDir() {
+    const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(moduleDir, "..", "..", "rules");
+}
+function digestRule(rule) {
+    return digestJson({
+        id: rule.id,
+        version: rule.version,
+        title: rule.title,
+        severity: rule.severity,
+        rationale: rule.rationale,
+        applies_when: rule.applies_when,
+        enforcement: rule.enforcement,
+    });
+}
+function digestJson(value) {
+    return `sha256:${createHash("sha256").update(stableStringify(value)).digest("hex")}`;
+}
+function stableStringify(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(stableStringify).join(",")}]`;
+    }
+    if (value && typeof value === "object") {
+        const entries = Object.entries(value)
+            .filter(([, entryValue]) => entryValue !== undefined)
+            .sort(([a], [b]) => a.localeCompare(b));
+        return `{${entries.map(([key, entryValue]) => `${JSON.stringify(key)}:${stableStringify(entryValue)}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+function confidenceField(value) {
+    if (value === "high" || value === "medium" || value === "low") {
+        return value;
+    }
+    throw new Error("confidence must be high, medium, or low.");
+}
+function signerField(value) {
+    if (value === "host-agent" || value === "human") {
+        return value;
+    }
+    throw new Error("signer must be host-agent or human.");
+}
+function evidenceField(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("evidence must be an object.");
+    }
+    return value;
+}