attention-manifest-protocol 0.4.0 → 0.4.2

package/lib/governance/perspectives.js

@@ -0,0 +1,340 @@
+import { GovernanceError, PerspectiveIds } from "./types.js";
+import { PerspectiveActivationTable } from "./matrix.js";
+/**
+ * The canonical registry. Order follows the governance template.
+ */
+export const PerspectiveRegistry = {
+    shareholders: {
+        id: "shareholders",
+        labelZh: "股东大会",
+        labelEn: "Shareholders",
+        layer: "strategic",
+        focus: ["goal authority", "final arbitration", "liability"],
+        frequency: "final arbitration only",
+        switchable: false,
+        directSwitch: false,
+        signsCredentials: false,
+        approve: ["goal.change", "liability.attribution", "final.ruling", "escalation.final"],
+        independentAudit: false,
+    },
+    board: {
+        id: "board",
+        labelZh: "董事会",
+        labelEn: "Board",
+        layer: "strategic",
+        focus: ["strategic goals", "risk appetite", "capability declarations"],
+        frequency: "low frequency or on demand",
+        switchable: false,
+        directSwitch: false,
+        signsCredentials: false,
+        approve: ["strategy.version", "capability.change", "budget.major-top-up", "arbitration.major", "escalation.strategic", "board.write"],
+        independentAudit: false,
+    },
+    supervisory: {
+        id: "supervisory",
+        labelZh: "监事会",
+        labelEn: "Supervisory board",
+        layer: "strategic",
+        focus: ["evidence traceability", "receipt self-consistency"],
+        frequency: "sampled per scenario",
+        switchable: false,
+        directSwitch: false,
+        signsCredentials: false,
+        approve: ["audit.evidence", "audit.archive"],
+        independentAudit: true,
+    },
+    "general-manager": {
+        id: "general-manager",
+        labelZh: "总经理",
+        labelEn: "General manager",
+        layer: "management",
+        focus: ["switch triggers", "budget consumption", "conflict detection", "scenario and mode approvals"],
+        frequency: "resident, high frequency",
+        switchable: true,
+        directSwitch: true,
+        signsCredentials: true,
+        approve: [
+            "credential.issue",
+            "manifest.derive",
+            "manifest.focus",
+            "scenario.judgement",
+            "complexity.grade",
+            "mode.weights",
+            "escalation.initiate",
+            "escalation.audit",
+            "arbitration.major",
+        ],
+        independentAudit: false,
+    },
+    "customer-service": {
+        id: "customer-service",
+        labelZh: "客服部",
+        labelEn: "Customer service",
+        layer: "execution",
+        focus: ["user intent", "ambiguities", "constraints", "acceptance criteria", "emotional signals"],
+        frequency: "task entry and closing",
+        switchable: true,
+        directSwitch: true,
+        signsCredentials: false,
+        approve: ["requirement.complete", "requirement.change", "requirement.satisfaction", "acceptance.criteria"],
+        independentAudit: false,
+    },
+    writing: {
+        id: "writing",
+        labelZh: "写作视角",
+        labelEn: "Writing desk",
+        layer: "execution",
+        focus: ["structure", "voice", "material selection", "revision"],
+        frequency: "activated by the writing scenario",
+        switchable: true,
+        directSwitch: true,
+        signsCredentials: false,
+        approve: [],
+        independentAudit: false,
+    },
+    strategy: {
+        id: "strategy",
+        labelZh: "战略部",
+        labelEn: "Strategy",
+        layer: "execution",
+        focus: ["task decomposition", "dependency structure", "risk points"],
+        frequency: "complex tasks",
+        switchable: true,
+        directSwitch: true,
+        signsCredentials: false,
+        approve: [],
+        independentAudit: false,
+    },
+    "human-resources": {
+        id: "human-resources",
+        labelZh: "人力资源部",
+        labelEn: "Human resources",
+        layer: "rule",
+        focus: ["capability fit", "perspective availability", "reliability priors"],
+        frequency: "planning and preparation",
+        switchable: false,
+        directSwitch: false,
+        signsCredentials: false,
+        approve: ["perspective.assignment", "perspective.routing", "perspective.readiness"],
+        independentAudit: false,
+    },
+    marketing: {
+        id: "marketing",
+        labelZh: "市场部",
+        labelEn: "Market research",
+        layer: "execution",
+        focus: ["external information needs", "environment assumptions", "competitor, user and policy signals"],
+        frequency: "per scenario and mode",
+        switchable: true,
+        directSwitch: true,
+        signsCredentials: false,
+        approve: [],
+        independentAudit: false,
+    },
+    technology: {
+        id: "technology",
+        labelZh: "技术部",
+        labelEn: "Technology",
+        layer: "execution",
+        focus: ["current subgoal", "tool returns", "error logs"],
+        frequency: "on demand",
+        switchable: true,
+        directSwitch: true,
+        signsCredentials: false,
+        approve: [],
+        independentAudit: false,
+    },
+    legal: {
+        id: "legal",
+        labelZh: "法务部",
+        labelEn: "Legal",
+        layer: "execution",
+        focus: ["behaviour-code compliance", "boundary signals", "injection traces"],
+        frequency: "pre-rules plus on demand",
+        switchable: true,
+        directSwitch: true,
+        signsCredentials: true,
+        approve: ["credential.compliance", "manifest.constraints", "manifest.evidence-floor", "manifest.waiver", "tool.high-risk", "board.write", "audit.behavior"],
+        independentAudit: false,
+    },
+    finance: {
+        id: "finance",
+        labelZh: "财务部",
+        labelEn: "Finance",
+        layer: "rule",
+        focus: ["three-ledger balances", "overrun signals", "elasticity use"],
+        frequency: "rule module",
+        switchable: false,
+        directSwitch: false,
+        signsCredentials: true,
+        approve: [
+            "budget.initial",
+            "budget.allocation",
+            "budget.freeze",
+            "budget.elasticity",
+            "budget.top-up",
+            "budget.settlement",
+            "budget.reserve",
+            "budget.major-top-up",
+            "audit.budget",
+        ],
+        independentAudit: false,
+    },
+    administration: {
+        id: "administration",
+        labelZh: "行政部",
+        labelEn: "Administration",
+        layer: "rule",
+        focus: ["log integrity", "archive state", "version chains"],
+        frequency: "infrastructure",
+        switchable: false,
+        directSwitch: false,
+        signsCredentials: false,
+        approve: ["audit.archive"],
+        independentAudit: false,
+    },
+    operations: {
+        id: "operations",
+        labelZh: "运营部",
+        labelEn: "Operations",
+        layer: "execution",
+        focus: ["phase transitions", "rollback triggers", "timeouts"],
+        frequency: "resident during execution",
+        switchable: true,
+        directSwitch: true,
+        signsCredentials: false,
+        approve: [],
+        independentAudit: false,
+    },
+};
+/**
+ * The standing perspectives of section 12.1 (the writing desk is a
+ * scenario-specific view and is excluded from the standing count).
+ */
+export const StandingPerspectives = [
+    "board",
+    "supervisory",
+    "general-manager",
+    "customer-service",
+    "strategy",
+    "marketing",
+    "technology",
+    "legal",
+    "operations",
+];
+/**
+ * Look up a perspective, failing closed for unknown ids.
+ */
+export const perspective = (id) => {
+    if (!PerspectiveIds.includes(id)) {
+        throw new GovernanceError("unknown-perspective", `${id} is not a registered perspective`);
+    }
+    return PerspectiveRegistry[id];
+};
+export const isKnownPerspective = (id) => PerspectiveIds.includes(id);
+/**
+ * Rule modules and infrastructure are not switchable perspectives.
+ */
+export const isRuleModule = (id) => PerspectiveRegistry[id].layer === "rule";
+/**
+ * Strategic perspectives are reached through escalation, never a same-level
+ * switch credential.
+ */
+export const requiresEscalation = (id) => PerspectiveRegistry[id].layer === "strategic";
+export const canApprove = (id, subject) => PerspectiveRegistry[id].approve.includes(subject);
+/**
+ * Who may approve a subject, in registry order (used for routing refusals).
+ */
+export const approversOf = (subject) => PerspectiveIds.filter((id) => PerspectiveRegistry[id].approve.includes(subject));
+/**
+ * A same-level switch credential is issued by the general manager to a
+ * non-strategic, directly switchable perspective.
+ */
+export const canIssueCredential = (from, to) => {
+    if (from === to) {
+        return false;
+    }
+    if (from !== "general-manager") {
+        return false;
+    }
+    const target = PerspectiveRegistry[to];
+    return target.directSwitch && target.switchable && target.layer === "execution";
+};
+/**
+ * Which strategic target an escalation type may reach.
+ */
+export const escalationTarget = (type) => {
+    switch (type) {
+        case "audit":
+            return "supervisory";
+        case "strategy":
+            return "board";
+        case "final":
+            return "shareholders";
+        case "compliance":
+            return "legal";
+        default:
+            return "general-manager";
+    }
+};
+/**
+ * Scenario activation for one perspective (spec section 9.8).
+ */
+export const activationFor = (id, scenario) => {
+    const plan = PerspectiveActivationTable[scenario];
+    if (plan.default.includes(id)) {
+        return "default";
+    }
+    if (plan.onDemand.includes(id)) {
+        return "on-demand";
+    }
+    return "dormant";
+};
+/**
+ * The activation plan for a scenario, with copies so callers cannot mutate the
+ * table.
+ */
+export const perspectivesForScenario = (scenario) => {
+    const plan = PerspectiveActivationTable[scenario];
+    return {
+        default: [...plan.default],
+        onDemand: [...plan.onDemand],
+        dormant: [...plan.dormant],
+        ...(plan.note === (void 0) ? {} : { note: plan.note }),
+    };
+};
+/**
+ * Registry self-check; used by checks and on first import in development.
+ */
+export const validatePerspectiveRegistry = () => {
+    const problems = [];
+    const seen = new Set();
+    for (let index = 0; index < PerspectiveIds.length; index += 1) {
+        const id = PerspectiveIds[index];
+        if (seen.has(id)) {
+            problems.push(`duplicate perspective id: ${id}`);
+        }
+        seen.add(id);
+        const definition = PerspectiveRegistry[id];
+        if (definition === (void 0)) {
+            problems.push(`missing registry row: ${id}`);
+            continue;
+        }
+        if (definition.id !== id) {
+            problems.push(`registry key ${id} disagrees with row id ${definition.id}`);
+        }
+        if (definition.layer === "rule" && definition.switchable) {
+            problems.push(`rule module ${id} must not be switchable`);
+        }
+        if (definition.layer === "strategic" && definition.directSwitch) {
+            problems.push(`strategic perspective ${id} must not be a direct switch target`);
+        }
+        if (definition.signsCredentials && !["general-manager", "legal", "finance"].includes(id)) {
+            problems.push(`${id} must not counter-sign credentials`);
+        }
+    }
+    if (!PerspectiveIds.includes("general-manager")) {
+        problems.push("the registry must contain the general manager");
+    }
+    return problems;
+};

package/lib/governance/signing.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Ed25519 adapter for governance objects.
+ *
+ * Governance sign-offs answer "which department approved this digest"; this
+ * module answers "who can prove they hold the key for that department". The two
+ * layers are deliberately separate: a deployment may run the governance layer
+ * without cryptography, and it may attach cryptography only where the host can
+ * manage keys.
+ *
+ * A signature covers `{signer, subject, subjectId, subjectVersion, digest}`, so a
+ * signature cannot be transplanted from one manifest or credential to another.
+ */
+import type { Digest, Id } from "../types/common.js";
+import type { KeyPair } from "../manifest/sign.js";
+/**
+ * Generic canonical-value signatures for transport envelopes and audit
+ * checkpoints. The governance-specific functions below bind a digest to a
+ * subject; these helpers only sign the canonical JSON of `value`.
+ */
+export declare const signCanonicalValue: (value: unknown, key: KeyPair) => Promise<string>;
+type VerifyCanonicalFn = (value: unknown, signature: string, publicKey: CryptoKey) => Promise<boolean>;
+export declare const verifyCanonicalValue: VerifyCanonicalFn;
+export interface GovernanceSigner {
+    signer: string;
+    key: KeyPair;
+}
+export interface GovernanceCryptoSignature {
+    signer: string;
+    kid: Id;
+    alg: "ed25519";
+    sig: string;
+    digest: Digest;
+}
+export type GovernanceSubject = "attention-manifest" | "switch-credential" | "audit-checkpoint" | "cooperation-message";
+export interface GovernanceSignatureBundle {
+    kind: "governance-signatures";
+    subject: GovernanceSubject;
+    subjectId: string;
+    subjectVersion?: number;
+    subjectDigest: Digest;
+    signatures: GovernanceCryptoSignature[];
+}
+export interface GovernanceVerification {
+    ok: boolean;
+    reasons: string[];
+}
+/**
+ * Public keys keyed by the governance signer name. Revocation is separate from
+ * deletion, so a revoked signer fails closed even if its key is still present.
+ *
+ * Rotation keeps the old key as a candidate until `retiresAt`, so signatures
+ * made before the rotation still verify during the overlap window.
+ */
+export interface GovernanceKeyRecord {
+    kid?: Id;
+    key: CryptoKey;
+    addedAt?: number;
+    retiresAt?: number;
+}
+export type KeyringAction = "add" | "rotate" | "revoke" | "revoke-kid" | "prune";
+export interface KeyringEvent {
+    action: KeyringAction;
+    signer: string;
+    kid?: Id;
+    at: number;
+}
+export type KeyringEventSink = (event: KeyringEvent) => void;
+export declare class GovernanceKeyring {
+    private readonly keys;
+    private readonly revoked;
+    private readonly revokedKids;
+    private readonly onEvent?;
+    constructor(options?: {
+        onEvent?: KeyringEventSink;
+    });
+    private emit;
+    add(signer: string, publicKey: CryptoKey, record?: {
+        kid?: Id;
+        at?: number;
+        retiresAt?: number;
+    }): void;
+    /**
+     * Add a new key and retire the previous ones after the overlap window.
+     */
+    rotate(signer: string, publicKey: CryptoKey, options: {
+        kid?: Id;
+        at: number;
+        overlapMs?: number;
+    }): void;
+    revoke(signer: string): void;
+    revokeKid(signer: string, kid: Id): void;
+    prune(at: number): void;
+    candidates(signer: string, kid?: Id, at?: number): CryptoKey[];
+    get(signer: string, kid?: Id, at?: number): CryptoKey | undefined;
+}
+type GenerateSignersFn = (signers: readonly string[], kidPrefix?: string) => Promise<GovernanceSigner[]>;
+export declare const generateGovernanceSigners: GenerateSignersFn;
+export declare const signGovernanceDigest: (input: {
+    signer: GovernanceSigner;
+    subject: GovernanceSubject;
+    subjectId: string;
+    subjectVersion?: number;
+    digest: Digest;
+}) => Promise<GovernanceCryptoSignature>;
+export declare const verifyGovernanceSignature: (input: {
+    signature: GovernanceCryptoSignature;
+    subject: GovernanceSubject;
+    subjectId: string;
+    subjectVersion?: number;
+    digest: Digest;
+    keyring: GovernanceKeyring;
+}) => Promise<GovernanceVerification>;
+export declare const signGovernanceObject: (input: {
+    subject: GovernanceSubject;
+    subjectId: string;
+    subjectVersion?: number;
+    digest: Digest;
+    signers: readonly GovernanceSigner[];
+}) => Promise<GovernanceSignatureBundle>;
+export declare const verifyGovernanceBundle: (input: {
+    bundle: GovernanceSignatureBundle;
+    expected: {
+        subject: GovernanceSubject;
+        subjectId: string;
+        subjectVersion?: number;
+        digest: Digest;
+    };
+    keyring: GovernanceKeyring;
+    requiredSigners?: readonly string[];
+}) => Promise<GovernanceVerification>;
+export {};