@cleocode/lafs 1.8.0

package/dist/src/cli.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * LAFS Conformance CLI — diagnostic/human-readable tool.
+ *
+ * This CLI is a **diagnostic utility** that validates envelopes and flags
+ * against the LAFS schema and conformance checks. It is NOT itself a
+ * LAFS-conformant envelope producer. Its output is for human consumption
+ * and CI pipelines, not for machine-to-machine chaining.
+ *
+ * Exemption: The CLI is exempt from LAFS envelope conformance requirements.
+ * Its output format is not a LAFS envelope and MUST NOT be validated as one.
+ *
+ * @task T042
+ * @epic T034
+ */
+import { readFile } from "node:fs/promises";
+import { runEnvelopeConformance, runFlagConformance } from "./conformance.js";
+function parseArgs(argv) {
+    const args = {};
+    for (let i = 0; i < argv.length; i += 1) {
+        const current = argv[i];
+        const next = argv[i + 1];
+        if (current === "--envelope" && next) {
+            args.envelopePath = next;
+            i += 1;
+        }
+        else if (current === "--flags" && next) {
+            args.flagsPath = next;
+            i += 1;
+        }
+    }
+    return args;
+}
+async function readJson(path) {
+    const content = await readFile(path, "utf8");
+    return JSON.parse(content);
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    const reports = [];
+    if (args.envelopePath) {
+        const envelope = await readJson(args.envelopePath);
+        reports.push({ name: "envelope", report: runEnvelopeConformance(envelope) });
+    }
+    if (args.flagsPath) {
+        const flags = await readJson(args.flagsPath);
+        reports.push({ name: "flags", report: runFlagConformance(flags) });
+    }
+    if (reports.length === 0) {
+        throw new Error("Provide --envelope and/or --flags JSON files.");
+    }
+    console.log(JSON.stringify({ success: true, reports }, null, 2));
+}
+main().catch((error) => {
+    console.error(JSON.stringify({
+        success: false,
+        error: {
+            code: "E_INTERNAL_UNEXPECTED",
+            message: error instanceof Error ? error.message : String(error)
+        }
+    }, null, 2));
+    process.exit(1);
+});

package/dist/src/compliance.d.ts

@@ -0,0 +1,31 @@
+import type { ConformanceReport, FlagInput, LAFSEnvelope } from "./types.js";
+import { type EnvelopeValidationResult } from "./validateEnvelope.js";
+export type ComplianceStage = "schema" | "envelope" | "flags" | "format";
+export interface ComplianceIssue {
+    stage: ComplianceStage;
+    message: string;
+    detail?: string;
+}
+export interface EnforceComplianceOptions {
+    checkConformance?: boolean;
+    checkFlags?: boolean;
+    flags?: FlagInput;
+    requireJsonOutput?: boolean;
+}
+export interface ComplianceResult {
+    ok: boolean;
+    envelope?: LAFSEnvelope;
+    validation: EnvelopeValidationResult;
+    envelopeConformance?: ConformanceReport;
+    flagConformance?: ConformanceReport;
+    issues: ComplianceIssue[];
+}
+export declare class ComplianceError extends Error {
+    readonly issues: ComplianceIssue[];
+    constructor(issues: ComplianceIssue[]);
+}
+export declare function enforceCompliance(input: unknown, options?: EnforceComplianceOptions): ComplianceResult;
+export declare function assertCompliance(input: unknown, options?: EnforceComplianceOptions): LAFSEnvelope;
+export declare function withCompliance<TArgs extends unknown[], TResult extends LAFSEnvelope>(producer: (...args: TArgs) => TResult | Promise<TResult>, options?: EnforceComplianceOptions): (...args: TArgs) => Promise<LAFSEnvelope>;
+export type ComplianceMiddleware = (envelope: LAFSEnvelope, next: () => LAFSEnvelope | Promise<LAFSEnvelope>) => Promise<LAFSEnvelope> | LAFSEnvelope;
+export declare function createComplianceMiddleware(options?: EnforceComplianceOptions): ComplianceMiddleware;

package/dist/src/compliance.js

@@ -0,0 +1,89 @@
+import { runEnvelopeConformance, runFlagConformance } from "./conformance.js";
+import { resolveOutputFormat } from "./flagSemantics.js";
+import { assertEnvelope, validateEnvelope } from "./validateEnvelope.js";
+export class ComplianceError extends Error {
+    issues;
+    constructor(issues) {
+        super(`LAFS compliance failed: ${issues.map((issue) => issue.message).join("; ")}`);
+        this.name = "ComplianceError";
+        this.issues = issues;
+    }
+}
+function conformanceIssues(report, stage) {
+    return report.checks
+        .filter((check) => !check.pass)
+        .map((check) => ({
+        stage,
+        message: `${check.name} failed`,
+        detail: check.detail,
+    }));
+}
+export function enforceCompliance(input, options = {}) {
+    const { checkConformance = true, checkFlags = false, flags, requireJsonOutput = false, } = options;
+    const issues = [];
+    const validation = validateEnvelope(input);
+    if (!validation.valid) {
+        issues.push(...validation.errors.map((error) => ({
+            stage: "schema",
+            message: "schema validation failed",
+            detail: error,
+        })));
+        return {
+            ok: false,
+            validation,
+            issues,
+        };
+    }
+    const envelope = assertEnvelope(input);
+    let envelopeConformance;
+    if (checkConformance) {
+        envelopeConformance = runEnvelopeConformance(envelope);
+        if (!envelopeConformance.ok) {
+            issues.push(...conformanceIssues(envelopeConformance, "envelope"));
+        }
+    }
+    let flagConformance;
+    if (checkFlags && flags) {
+        flagConformance = runFlagConformance(flags);
+        if (!flagConformance.ok) {
+            issues.push(...conformanceIssues(flagConformance, "flags"));
+        }
+    }
+    if (requireJsonOutput) {
+        const resolved = resolveOutputFormat(flags ?? {});
+        if (resolved.format !== "json") {
+            issues.push({
+                stage: "format",
+                message: "non-json output format resolved",
+                detail: `resolved format is ${resolved.format}`,
+            });
+        }
+    }
+    return {
+        ok: issues.length === 0,
+        envelope,
+        validation,
+        envelopeConformance,
+        flagConformance,
+        issues,
+    };
+}
+export function assertCompliance(input, options = {}) {
+    const result = enforceCompliance(input, options);
+    if (!result.ok || !result.envelope) {
+        throw new ComplianceError(result.issues);
+    }
+    return result.envelope;
+}
+export function withCompliance(producer, options = {}) {
+    return async (...args) => {
+        const envelope = await producer(...args);
+        return assertCompliance(envelope, options);
+    };
+}
+export function createComplianceMiddleware(options = {}) {
+    return async (_envelope, next) => {
+        const candidate = await next();
+        return assertCompliance(candidate, options);
+    };
+}

package/dist/src/conformance.d.ts

@@ -0,0 +1,7 @@
+import type { ConformanceReport, FlagInput } from "./types.js";
+import { type ConformanceTier } from "./conformanceProfiles.js";
+export interface EnvelopeConformanceOptions {
+    tier?: ConformanceTier;
+}
+export declare function runEnvelopeConformance(envelope: unknown, options?: EnvelopeConformanceOptions): ConformanceReport;
+export declare function runFlagConformance(flags: FlagInput): ConformanceReport;

package/dist/src/conformance.js

@@ -0,0 +1,248 @@
+import { getTransportMapping, isRegisteredErrorCode, getRegistryCode } from "./errorRegistry.js";
+import { resolveOutputFormat, LAFSFlagError } from "./flagSemantics.js";
+import { isAgentAction, isMVILevel } from "./types.js";
+import { getChecksForTier } from "./conformanceProfiles.js";
+import { validateEnvelope } from "./validateEnvelope.js";
+function pushCheck(checks, name, pass, detail) {
+    checks.push({ name, pass, ...(detail ? { detail } : {}) });
+}
+export function runEnvelopeConformance(envelope, options = {}) {
+    const checks = [];
+    const validation = validateEnvelope(envelope);
+    pushCheck(checks, "envelope_schema_valid", validation.valid, validation.valid ? undefined : validation.errors.join("; "));
+    if (!validation.valid) {
+        return { ok: false, checks };
+    }
+    const typed = envelope;
+    // envelope_invariants: success=true allows error to be null OR omitted;
+    // success=false requires error to be a non-null object.
+    // result MAY be non-null on error — validation tools (linters, type checkers)
+    // need to return actionable data (e.g., suggestedFix) alongside the error.
+    const invariant = typed.success
+        ? typed.error == null // null or undefined (omitted) both valid for success
+        : typed.error != null; // error must be present, result is optional
+    pushCheck(checks, "envelope_invariants", invariant, invariant
+        ? undefined
+        : typed.success
+            ? "success=true but error is present and non-null"
+            : "success=false requires error to be a non-null object");
+    // error_code_registered: only checked when error is present (error is optional when success=true)
+    if (typed.error) {
+        const registered = isRegisteredErrorCode(typed.error.code);
+        pushCheck(checks, "error_code_registered", registered, registered ? undefined : `unregistered code: ${typed.error.code}`);
+    }
+    else {
+        pushCheck(checks, "error_code_registered", true, "error field absent or null — skipped (optional when success=true)");
+    }
+    // agent_action_valid: if error.agentAction is present, it must be a valid LAFSAgentAction
+    if (typed.error && typed.error.agentAction !== undefined) {
+        const valid = isAgentAction(typed.error.agentAction);
+        pushCheck(checks, "agent_action_valid", valid, valid ? undefined : `invalid agentAction: ${String(typed.error.agentAction)}`);
+    }
+    else {
+        pushCheck(checks, "agent_action_valid", true, "agentAction absent — skipped");
+    }
+    // error_registry_agent_action: if error code is registered and agentAction is present,
+    // check if it matches the registry default (warning-level, not a hard failure)
+    if (typed.error && typed.error.agentAction !== undefined && isRegisteredErrorCode(typed.error.code)) {
+        const registryEntry = getRegistryCode(typed.error.code);
+        const registryAction = registryEntry?.["agentAction"];
+        if (registryAction) {
+            const matches = typed.error.agentAction === registryAction;
+            pushCheck(checks, "error_registry_agent_action", true, // always passes — advisory only
+            matches
+                ? undefined
+                : `agentAction "${typed.error.agentAction}" differs from registry default "${registryAction}" for ${typed.error.code} (advisory)`);
+        }
+        else {
+            pushCheck(checks, "error_registry_agent_action", true, "registry entry has no default agentAction — skipped");
+        }
+    }
+    else {
+        pushCheck(checks, "error_registry_agent_action", true, typed.error ? "agentAction absent or code unregistered — skipped" : "no error present — skipped");
+    }
+    // transport_mapping_consistent: when an error is present, ensure the code has
+    // a transport-specific mapping in the registry for the declared transport.
+    if (typed.error) {
+        if (typed._meta.transport === "sdk") {
+            pushCheck(checks, "transport_mapping_consistent", true, "sdk transport does not require external status-code mapping");
+        }
+        else {
+            const mapping = getTransportMapping(typed.error.code, typed._meta.transport);
+            const mappingOk = mapping !== null;
+            pushCheck(checks, "transport_mapping_consistent", mappingOk, mappingOk
+                ? undefined
+                : `no ${typed._meta.transport} mapping found for code ${typed.error.code}`);
+        }
+    }
+    else {
+        pushCheck(checks, "transport_mapping_consistent", true, "no error present — mapping check skipped");
+    }
+    // context_mutation_failure: if the producer marks context as required for a
+    // mutation operation, missing context must fail with a context error code.
+    {
+        const ext = (typed._extensions ?? {});
+        const contextObj = (ext["context"] ?? {});
+        const lafsObj = (ext["lafs"] ?? {});
+        const contextRequired = ext["lafsContextRequired"] === true ||
+            contextObj["required"] === true ||
+            lafsObj["contextRequired"] === true;
+        if (!contextRequired) {
+            pushCheck(checks, "context_mutation_failure", true, "context not marked required — skipped");
+        }
+        else {
+            const hasContextIdentity = typed._meta.contextVersion > 0 || Boolean(typed._meta.sessionId);
+            if (typed.success) {
+                const pass = hasContextIdentity;
+                pushCheck(checks, "context_mutation_failure", pass, pass ? undefined : "context required but missing identity (expect E_CONTEXT_MISSING)");
+            }
+            else {
+                const code = typed.error?.code;
+                const pass = code === "E_CONTEXT_MISSING" || code === "E_CONTEXT_STALE";
+                pushCheck(checks, "context_mutation_failure", pass, pass
+                    ? undefined
+                    : `context required failures should return E_CONTEXT_MISSING or E_CONTEXT_STALE, got ${String(code)}`);
+            }
+        }
+    }
+    const mviValid = isMVILevel(typed._meta.mvi);
+    pushCheck(checks, "meta_mvi_present", mviValid, mviValid ? undefined : `invalid mvi level: ${String(typed._meta.mvi)}`);
+    pushCheck(checks, "meta_strict_present", typeof typed._meta.strict === "boolean");
+    // strict_mode_behavior: when strict=true, the envelope MUST NOT contain
+    // explicit null for optional fields that can be omitted (page, error on success).
+    if (typed._meta.strict) {
+        const obj = envelope;
+        const hasExplicitNullError = typed.success && "error" in obj && obj["error"] === null;
+        const hasExplicitNullPage = "page" in obj && obj["page"] === null;
+        const strictClean = !hasExplicitNullError && !hasExplicitNullPage;
+        pushCheck(checks, "strict_mode_behavior", strictClean, strictClean
+            ? undefined
+            : "strict mode: optional fields should be omitted rather than set to null");
+    }
+    // pagination_mode_consistent: when page is present and is an object, verify
+    // that the fields present match the declared pagination mode.
+    if (typed.page && typeof typed.page === "object") {
+        const page = typed.page;
+        const mode = page["mode"];
+        let consistent = true;
+        let detail;
+        if (mode === "cursor") {
+            if (page["offset"] !== undefined) {
+                consistent = false;
+                detail = "cursor mode should not include offset field";
+            }
+        }
+        else if (mode === "offset") {
+            if (page["nextCursor"] !== undefined) {
+                consistent = false;
+                detail = "offset mode should not include nextCursor field";
+            }
+        }
+        else if (mode === "none") {
+            const extraFields = Object.keys(page).filter((k) => k !== "mode");
+            if (extraFields.length > 0) {
+                consistent = false;
+                detail = `none mode should only have mode field, found: ${extraFields.join(", ")}`;
+            }
+        }
+        pushCheck(checks, "pagination_mode_consistent", consistent, consistent ? undefined : detail);
+    }
+    else {
+        pushCheck(checks, "pagination_mode_consistent", true, "page absent — skipped");
+    }
+    // strict_mode_enforced: verify the schema enforces additional-property rules.
+    // When strict=true, extra top-level properties must be rejected by validation.
+    // When strict=false, extra top-level properties must be allowed.
+    {
+        const extraPropEnvelope = { ...envelope, _unknown_extra: true };
+        const extraResult = validateEnvelope(extraPropEnvelope);
+        if (typed._meta.strict) {
+            pushCheck(checks, "strict_mode_enforced", !extraResult.valid, extraResult.valid ? "strict=true but additional properties were accepted" : undefined);
+        }
+        else {
+            pushCheck(checks, "strict_mode_enforced", extraResult.valid, !extraResult.valid ? "strict=false but additional properties were rejected" : undefined);
+        }
+    }
+    // context_preservation_valid: validate monotonic context version behavior and
+    // context-constraint integrity when a context ledger extension is present.
+    {
+        const ext = (typed._extensions ?? {});
+        const ledger = (ext["contextLedger"] ?? ext["context"]);
+        if (!ledger || typeof ledger !== "object") {
+            pushCheck(checks, "context_preservation_valid", true, "context ledger absent — skipped");
+        }
+        else {
+            const version = ledger["version"];
+            const previousVersion = ledger["previousVersion"];
+            const removedConstraints = ledger["removedConstraints"];
+            const hasNumericVersion = typeof version === "number";
+            const matchesEnvelopeVersion = hasNumericVersion && version === typed._meta.contextVersion;
+            const monotonicFromPrevious = typeof previousVersion !== "number" || (hasNumericVersion && version >= previousVersion);
+            const constraintsPreserved = !Array.isArray(removedConstraints) || removedConstraints.length === 0 || !typed.success;
+            let pass = matchesEnvelopeVersion && monotonicFromPrevious && constraintsPreserved;
+            let detail;
+            if (!hasNumericVersion) {
+                pass = false;
+                detail = "context ledger version must be numeric";
+            }
+            else if (!matchesEnvelopeVersion) {
+                detail = `context version mismatch: ledger=${String(version)} envelope=${typed._meta.contextVersion}`;
+            }
+            else if (!monotonicFromPrevious) {
+                detail = `non-monotonic context version: previous=${String(previousVersion)} current=${String(version)}`;
+            }
+            else if (!constraintsPreserved) {
+                detail = "context constraint removal detected on successful response";
+            }
+            // Error-path validation for stale/missing context signaling.
+            if (!typed.success && typed.error && ledger["required"] === true) {
+                const stale = ledger["stale"] === true;
+                if (stale && typed.error.code !== "E_CONTEXT_STALE") {
+                    pass = false;
+                    detail = `stale context should return E_CONTEXT_STALE, got ${typed.error.code}`;
+                }
+                if (!stale && typed.error.code !== "E_CONTEXT_MISSING" && typed.error.code !== "E_CONTEXT_STALE") {
+                    pass = false;
+                    detail = `required context failure should return E_CONTEXT_MISSING or E_CONTEXT_STALE, got ${typed.error.code}`;
+                }
+            }
+            pushCheck(checks, "context_preservation_valid", pass, detail);
+        }
+    }
+    const tier = options.tier;
+    if (!tier) {
+        return { ok: checks.every((check) => check.pass), checks };
+    }
+    const allowed = new Set(getChecksForTier(tier));
+    const tierChecks = checks.filter((check) => allowed.has(check.name));
+    return { ok: tierChecks.every((check) => check.pass), checks: tierChecks };
+}
+export function runFlagConformance(flags) {
+    const checks = [];
+    try {
+        const resolved = resolveOutputFormat(flags);
+        pushCheck(checks, "flag_conflict_rejected", !(flags.humanFlag && flags.jsonFlag));
+        // Protocol-default check: when nothing is specified (source === "default"),
+        // the protocol requires JSON as the default format.
+        const isProtocolDefault = resolved.source === "default";
+        pushCheck(checks, "json_protocol_default", !isProtocolDefault || resolved.format === "json", isProtocolDefault && resolved.format !== "json"
+            ? `protocol default should be json, got ${resolved.format}`
+            : undefined);
+        // Config-override check: when a project or user default is active,
+        // the resolved format must match the config-provided value.
+        const hasConfigOverride = resolved.source === "project" || resolved.source === "user";
+        const expectedOverride = resolved.source === "project" ? flags.projectDefault : flags.userDefault;
+        pushCheck(checks, "config_override_respected", !hasConfigOverride || resolved.format === expectedOverride, hasConfigOverride && resolved.format !== expectedOverride
+            ? `config override expected ${String(expectedOverride)}, got ${resolved.format}`
+            : undefined);
+    }
+    catch (error) {
+        if (error instanceof LAFSFlagError && error.code === "E_FORMAT_CONFLICT") {
+            pushCheck(checks, "flag_conflict_rejected", true);
+            return { ok: checks.every((check) => check.pass), checks };
+        }
+        pushCheck(checks, "flag_resolution", false, error instanceof Error ? error.message : String(error));
+        return { ok: false, checks };
+    }
+    return { ok: checks.every((check) => check.pass), checks };
+}

package/dist/src/conformanceProfiles.d.ts

@@ -0,0 +1,11 @@
+export type ConformanceTier = "core" | "standard" | "complete";
+export interface ConformanceProfiles {
+    version: string;
+    tiers: Record<ConformanceTier, string[]>;
+}
+export declare function getConformanceProfiles(): ConformanceProfiles;
+export declare function getChecksForTier(tier: ConformanceTier): string[];
+export declare function validateConformanceProfiles(availableChecks: string[]): {
+    valid: boolean;
+    errors: string[];
+};

package/dist/src/conformanceProfiles.js

@@ -0,0 +1,34 @@
+import profilesJson from "../schemas/v1/conformance-profiles.json" with { type: "json" };
+export function getConformanceProfiles() {
+    return profilesJson;
+}
+export function getChecksForTier(tier) {
+    const profiles = getConformanceProfiles();
+    return profiles.tiers[tier] ?? [];
+}
+export function validateConformanceProfiles(availableChecks) {
+    const profiles = getConformanceProfiles();
+    const errors = [];
+    const core = new Set(profiles.tiers.core);
+    const standard = new Set(profiles.tiers.standard);
+    const complete = new Set(profiles.tiers.complete);
+    for (const check of core) {
+        if (!standard.has(check)) {
+            errors.push(`standard tier must include core check: ${check}`);
+        }
+    }
+    for (const check of standard) {
+        if (!complete.has(check)) {
+            errors.push(`complete tier must include standard check: ${check}`);
+        }
+    }
+    const known = new Set(availableChecks);
+    for (const [tier, checks] of Object.entries(profiles.tiers)) {
+        for (const check of checks) {
+            if (!known.has(check)) {
+                errors.push(`unknown check in ${tier} tier: ${check}`);
+            }
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}

package/dist/src/deprecationRegistry.d.ts

@@ -0,0 +1,13 @@
+import type { LAFSEnvelope, Warning } from "./types.js";
+export interface DeprecationEntry {
+    id: string;
+    code: string;
+    message: string;
+    deprecated: string;
+    replacement?: string;
+    removeBy: string;
+    detector: (envelope: LAFSEnvelope) => boolean;
+}
+export declare function getDeprecationRegistry(): DeprecationEntry[];
+export declare function detectDeprecatedEnvelopeFields(envelope: LAFSEnvelope): Warning[];
+export declare function emitDeprecationWarnings(envelope: LAFSEnvelope): LAFSEnvelope;

package/dist/src/deprecationRegistry.js

@@ -0,0 +1,39 @@
+const DEPRECATION_REGISTRY = [
+    {
+        id: "meta-mvi-boolean",
+        code: "W_DEPRECATED_META_MVI_BOOLEAN",
+        message: "_meta.mvi boolean values are deprecated",
+        deprecated: "1.0.0",
+        replacement: "Use _meta.mvi as one of: minimal|standard|full|custom",
+        removeBy: "2.0.0",
+        detector: (envelope) => typeof envelope._meta.mvi === "boolean",
+    },
+];
+export function getDeprecationRegistry() {
+    return DEPRECATION_REGISTRY;
+}
+export function detectDeprecatedEnvelopeFields(envelope) {
+    return getDeprecationRegistry()
+        .filter((entry) => entry.detector(envelope))
+        .map((entry) => ({
+        code: entry.code,
+        message: entry.message,
+        deprecated: entry.deprecated,
+        replacement: entry.replacement,
+        removeBy: entry.removeBy,
+    }));
+}
+export function emitDeprecationWarnings(envelope) {
+    const detected = detectDeprecatedEnvelopeFields(envelope);
+    if (detected.length === 0) {
+        return envelope;
+    }
+    const existingWarnings = envelope._meta.warnings ?? [];
+    return {
+        ...envelope,
+        _meta: {
+            ...envelope._meta,
+            warnings: [...existingWarnings, ...detected],
+        },
+    };
+}