attention-manifest-protocol 0.4.0 → 0.4.2

package/lib/governance/types.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Shared vocabulary for the attention-governance layer.
+ *
+ * The governance layer implements the nine constructs described by the
+ * Attention Manifest Protocol: the attention manifest, three-layer context,
+ * perspective registry, switch credential, Bayesian control, legal behaviour
+ * norms, three-ledger budget, scenario x interaction-mode matrix, and the
+ * seven-phase workflow with approvals.
+ *
+ * This module holds only value types, constants and the shared error. Every
+ * other governance module depends on it; it depends on none of them, which
+ * keeps the layer acyclic.
+ */
+import type { Budget, Digest, Id, Ref, Tier, Timestamp } from "../types/common.js";
+export type { Budget, Digest, Id, Ref, Tier, Timestamp } from "../types/common.js";
+/**
+ * The five canonical scenarios. They replace the earlier eight-kind mix as the
+ * governance label; `src/governance/matrix.ts` keeps an explicit adapter for
+ * the legacy kinds so context profiling still works.
+ */
+export type ScenarioId = "chat" | "writing" | "office" | "research" | "engineering";
+export declare const ScenarioIds: readonly ScenarioId[];
+/**
+ * The four interaction modes. `diverge` is the governance name for the
+ * existing `inspire` interaction mode; they are bridged, not duplicated.
+ */
+export type ModeId = "affect" | "think" | "diverge" | "converge";
+export declare const ModeIds: readonly ModeId[];
+/**
+ * A normalized weight vector: every entry is in [0, 1] and the sum is 1.
+ */
+export type ModeWeights = Record<ModeId, number>;
+/**
+ * The thirteen perspectives of the governance template.
+ *
+ * Finance, human resources and administration are rule modules or
+ * infrastructure, not switchable perspectives; they are still addressable as
+ * approving or signing departments.
+ */
+export type PerspectiveId = "shareholders" | "board" | "supervisory" | "general-manager" | "customer-service" | "writing" | "strategy" | "human-resources" | "marketing" | "technology" | "legal" | "finance" | "administration" | "operations";
+export declare const PerspectiveIds: readonly PerspectiveId[];
+/**
+ * Strategic and management layers are dormant or resident; execution
+ * perspectives are activated per task; rule modules are always on.
+ */
+export type PerspectiveLayer = "strategic" | "management" | "execution" | "rule";
+/**
+ * How a perspective participates in a scenario (spec section 9.8).
+ */
+export type Activation = "default" | "on-demand" | "dormant";
+/**
+ * Attention budget elasticity (spec section 9.6).
+ */
+export type Elasticity = "low" | "medium" | "high";
+/**
+ * Escalation trigger sensitivity (spec section 9.7).
+ */
+export type Sensitivity = "very-low" | "low" | "medium" | "high";
+export declare const SensitivityRank: Record<Sensitivity, number>;
+/**
+ * Legal gate strictness per scenario (spec section 7.3).
+ */
+export type GateStrictness = "loose" | "medium" | "medium-strict" | "strict";
+/**
+ * Which ledger a budget binding or charge belongs to (spec section 8).
+ * `agent` is a sub-agent's own quota, funded by a transfer from its parent.
+ */
+export type LedgerScope = "global" | "perspective" | "agent" | "reserve";
+/**
+ * Governance evidence floors use their own order (F1 strongest) so the
+ * description's "T1/T2/T3" never collides with the protocol's T0-T4 strength
+ * order. `FloorTier` maps them onto the existing tier system.
+ */
+export type EvidenceFloor = "F1" | "F2" | "F3";
+export declare const EvidenceFloorIds: readonly EvidenceFloor[];
+/**
+ * Minimum protocol tier that satisfies each governance floor.
+ *
+ * The description uses T1 as the strictest floor, while AMP's T0-T4 axis is
+ * strictly increasing in strength (T1 sourced, T2 observed, T3 tested). The
+ * mapping keeps the description's intent: F1 demands tested evidence, F2
+ * observed evidence, F3 sourced evidence.
+ */
+export declare const FloorTier: Record<EvidenceFloor, Tier>;
+export declare const TierRank: Record<Tier, number>;
+export declare const FloorRank: Record<EvidenceFloor, number>;
+/**
+ * Elasticity limits. The specification fixes the high (auto +50%, post audit)
+ * and low (freeze beyond +20%) cases; medium is an explicit engineering
+ * choice: approval-gated up to +35% and audited afterwards.
+ */
+export interface ElasticityLimit {
+    /**
+     * Fraction of the cap that may be appended without an approval.
+     */
+    autoRatio: number;
+    /**
+     * Hard ceiling; beyond it the ledger freezes.
+     */
+    hardRatio: number;
+    /**
+     * Whether spending between cap and hardRatio needs a finance approval.
+     */
+    requiresApproval: boolean;
+    /**
+     * Whether appended spend is settled by a post-hoc audit.
+     */
+    postAudit: boolean;
+}
+export declare const ElasticityLimits: Record<Elasticity, ElasticityLimit>;
+/**
+ * Behaviour constraints injected by the legal department into a manifest or a
+ * switch credential (spec section 7.2).
+ */
+export interface BehaviorConstraints {
+    allowed: string[];
+    forbidden: string[];
+    obligations: string[];
+    escalation: string[];
+    /**
+     * Evidence floor the legal department insists on, possibly stricter than
+     * the scenario x mode floor.
+     */
+    evidence: EvidenceFloor;
+}
+/**
+ * A governance sign-off. It is deliberately not a cryptographic signature:
+ * the protocol signs the digest of the object and records which department
+ * approved it, so a missing counter-signature is visible in an audit.
+ */
+export type SignoffRole = "issuer" | "legal" | "finance" | "board" | "human";
+export interface Signoff {
+    role: SignoffRole;
+    by: PerspectiveId;
+    at: Timestamp;
+    digest: Digest;
+}
+/**
+ * An unsigned sign-off as supplied by a caller; `issue*` fills in the digest
+ * after computing it, so a caller cannot accidentally sign the wrong body.
+ */
+export interface SignerInput {
+    role: SignoffRole;
+    by: PerspectiveId;
+    at: Timestamp;
+}
+/**
+ * A versioned manifest reference, safe to copy between layers.
+ */
+export interface ManifestRef {
+    id: Id;
+    version: number;
+}
+/**
+ * An escalation request carried by a receipt or a workflow record.
+ */
+export interface EscalationRef {
+    to: PerspectiveId;
+    reason: string;
+}
+/**
+ * A verification result. Codes are stable; detail is for humans.
+ */
+export interface VerificationVerdict {
+    ok: boolean;
+    code?: string;
+    detail?: string;
+}
+/**
+ * A credential's budget quota and elasticity.
+ */
+export interface CredentialBudget {
+    quota: Budget;
+    elasticity: Elasticity;
+}
+/**
+ * Approval subjects from the responsibility table (spec section 10).
+ */
+export type ApprovalSubject = "budget.initial" | "budget.allocation" | "budget.freeze" | "budget.elasticity" | "budget.top-up" | "budget.settlement" | "budget.reserve" | "budget.major-top-up" | "credential.issue" | "credential.compliance" | "manifest.derive" | "manifest.constraints" | "manifest.evidence-floor" | "manifest.focus" | "manifest.waiver" | "mode.weights" | "scenario.judgement" | "complexity.grade" | "perspective.assignment" | "perspective.routing" | "perspective.readiness" | "escalation.initiate" | "escalation.audit" | "escalation.strategic" | "escalation.final" | "strategy.version" | "capability.change" | "arbitration.major" | "audit.evidence" | "audit.behavior" | "audit.budget" | "audit.archive" | "requirement.complete" | "requirement.change" | "requirement.satisfaction" | "acceptance.criteria" | "goal.change" | "liability.attribution" | "final.ruling" | "tool.high-risk" | "board.write" | "freeze.appeal";
+/**
+ * A recorded approval. `granted: false` is a rejection, not an absence.
+ */
+export interface ApprovalGrant {
+    id: Id;
+    subject: ApprovalSubject;
+    by: PerspectiveId;
+    at: Timestamp;
+    granted: boolean;
+    note?: string;
+}
+/**
+ * Budget arithmetic is per dimension; these are the dimensions a ledger can
+ * cap. A missing cap means "not metered on this dimension".
+ */
+export type BudgetDimension = "tokens" | "ms" | "calls" | "interrupts" | "money";
+export declare const BudgetDimensions: readonly BudgetDimension[];
+export type GovernanceCode = "invalid-scenario" | "invalid-mode-weights" | "unknown-perspective" | "manifest-expired" | "manifest-scope" | "manifest-unsigned" | "manifest-self-signed" | "manifest-version-conflict" | "manifest-rederive-required" | "approval-required" | "approval-not-permitted" | "approval-self" | "credential-incomplete" | "credential-invalid" | "credential-expired" | "credential-not-yet-valid" | "credential-tampered" | "credential-scope" | "credential-target" | "credential-revoked" | "credential-manifest" | "budget-frozen" | "budget-invalid" | "budget-frozen" | "budget-exhausted" | "budget-reserve" | "legal-frozen" | "legal-breaker" | "workflow-phase" | "workflow-step" | "workflow-artifact" | "context-denied" | "registry-invalid" | "probability-invalid";
+/**
+ * A fail-closed governance rejection: the caller gets a code, not a silently
+ * degraded policy.
+ */
+export declare class GovernanceError extends Error {
+    readonly code: GovernanceCode;
+    constructor(code: GovernanceCode, detail: string);
+}
+/**
+ * Stable key for a Ref so scopes can be compared without object identity.
+ */
+export declare const refKey: (ref: Ref) => string;
+/**
+ * A shallow read-only copy of a Budget with every dimension defaulted to zero.
+ */
+export declare const budgetTotals: (budget: Budget) => Required<Budget>;
+/**
+ * Description-only digest used when a caller does not have the full object;
+ * never used for integrity checks.
+ */
+export declare const auditLine: (parts: readonly string[]) => string;

package/lib/governance/types.js

@@ -0,0 +1,72 @@
+export const ScenarioIds = ["chat", "writing", "office", "research", "engineering"];
+export const ModeIds = ["affect", "think", "diverge", "converge"];
+export const PerspectiveIds = [
+    "shareholders",
+    "board",
+    "supervisory",
+    "general-manager",
+    "customer-service",
+    "writing",
+    "strategy",
+    "human-resources",
+    "marketing",
+    "technology",
+    "legal",
+    "finance",
+    "administration",
+    "operations",
+];
+export const SensitivityRank = { "very-low": 0, low: 1, medium: 2, high: 3 };
+export const EvidenceFloorIds = ["F1", "F2", "F3"];
+/**
+ * Minimum protocol tier that satisfies each governance floor.
+ *
+ * The description uses T1 as the strictest floor, while AMP's T0-T4 axis is
+ * strictly increasing in strength (T1 sourced, T2 observed, T3 tested). The
+ * mapping keeps the description's intent: F1 demands tested evidence, F2
+ * observed evidence, F3 sourced evidence.
+ */
+export const FloorTier = {
+    F1: "T3",
+    F2: "T2",
+    F3: "T1",
+};
+export const TierRank = { T0: 0, T1: 1, T2: 2, T3: 3, T4: 4 };
+export const FloorRank = { F1: 0, F2: 1, F3: 2 };
+export const ElasticityLimits = {
+    low: { autoRatio: 0.2, hardRatio: 0.2, requiresApproval: false, postAudit: false },
+    medium: { autoRatio: 0, hardRatio: 0.35, requiresApproval: true, postAudit: true },
+    high: { autoRatio: 0.5, hardRatio: 0.5, requiresApproval: false, postAudit: true },
+};
+export const BudgetDimensions = ["tokens", "ms", "calls", "interrupts", "money"];
+/**
+ * A fail-closed governance rejection: the caller gets a code, not a silently
+ * degraded policy.
+ */
+export class GovernanceError extends Error {
+    code;
+    constructor(code, detail) {
+        super(`${code}: ${detail}`);
+        this.name = "GovernanceError";
+        this.code = code;
+    }
+}
+/**
+ * Stable key for a Ref so scopes can be compared without object identity.
+ */
+export const refKey = (ref) => `${ref.kind}:${ref.id}`;
+/**
+ * A shallow read-only copy of a Budget with every dimension defaulted to zero.
+ */
+export const budgetTotals = (budget) => ({
+    tokens: budget.tokens ?? 0,
+    ms: budget.ms ?? 0,
+    calls: budget.calls ?? 0,
+    interrupts: budget.interrupts ?? 0,
+    money: budget.money ?? 0,
+});
+/**
+ * Description-only digest used when a caller does not have the full object;
+ * never used for integrity checks.
+ */
+export const auditLine = (parts) => parts.join(" | ");

package/lib/governance/workflow.d.ts

@@ -0,0 +1,174 @@
+/**
+ * The seven-phase workflow with approvals (spec section 11).
+ *
+ * The workflow is the only place that decides whether a phase may advance. It
+ * enforces three rules that the rest of the protocol depends on:
+ *   - an approval cannot be issued by the perspective that requested it;
+ *   - a phase gate needs its artefacts and its approvals, not just a mood;
+ *   - execution cannot start without a triple-signed switch credential.
+ *
+ * The phase table is data, so a change to a step is reviewable as a diff.
+ */
+import type { Id, Timestamp } from "../types/common.js";
+import type { ApprovalGrant, ApprovalSubject, ModeWeights, PerspectiveId, ScenarioId, SignoffRole } from "./types.js";
+import type { SwitchCredential } from "./credential.js";
+export type PhaseId = "intake" | "planning" | "preparation" | "execution" | "audit" | "escalation" | "archive";
+export declare const PhaseOrder: readonly PhaseId[];
+export type EscalationType = "audit" | "strategy" | "final" | "compliance";
+/**
+ * One step of a phase: who acts, what they do, what they produce.
+ */
+export interface StepSpec {
+    id: string;
+    phase: PhaseId;
+    owner: PerspectiveId;
+    action: string;
+    produces: string;
+    optional?: boolean;
+}
+export interface Artifact {
+    id: Id;
+    kind: string;
+    by: PerspectiveId;
+    at: Timestamp;
+    signoffs?: SignoffRole[];
+    digest?: string;
+    note?: string;
+}
+export interface WorkflowApproval extends ApprovalGrant {
+    requestedBy: PerspectiveId;
+}
+export interface PhaseTransition {
+    from: PhaseId | "none";
+    to: PhaseId;
+    by: PerspectiveId;
+    at: Timestamp;
+    note: string;
+}
+export interface EscalationRecord {
+    type: EscalationType;
+    reason: string;
+    evidenceRefs: number;
+    by: PerspectiveId;
+    at: Timestamp;
+    target: PerspectiveId;
+    returnPhase: PhaseId;
+}
+export interface WorkflowState {
+    id: Id;
+    scenario: ScenarioId;
+    modes: ModeWeights;
+    phase: PhaseId;
+    status: "open" | "blocked" | "complete" | "terminated";
+    completedSteps: string[];
+    artifacts: Artifact[];
+    approvals: WorkflowApproval[];
+    manifest?: {
+        id: Id;
+        version: number;
+    };
+    credential?: {
+        id: Id;
+        signoffs: SignoffRole[];
+        expires: Timestamp;
+        digest: string;
+    };
+    escalation?: EscalationRecord;
+    history: PhaseTransition[];
+    blockedReason?: string;
+}
+export interface StartInput {
+    id: Id;
+    scenario: ScenarioId;
+    modes?: Partial<ModeWeights>;
+    at: Timestamp;
+}
+/**
+ * The phase table. Actions are short because the artefacts carry the detail.
+ */
+export declare const PhaseSteps: Record<PhaseId, readonly StepSpec[]>;
+/**
+ * The workflow engine. It is deliberately linear: `escalate` side-branches and
+ * `resume` returns, and `advance` is the only door to the next phase.
+ */
+export declare class Workflow {
+    private readonly state;
+    private counter;
+    constructor(state: WorkflowState);
+    static start(input: StartInput): Workflow;
+    current(): WorkflowState;
+    steps(): StepSpec[];
+    /**
+     * Complete one step of the current phase and record its artefact.
+     */
+    complete(stepId: string, by: PerspectiveId, at: Timestamp, note?: string): WorkflowState;
+    /**
+     * Complete a step and record a richer artefact in one operation. Use this
+     * when the artefact carries sign-offs or a digest (a credential, an audit
+     * receipt); `complete` records the plain artefact.
+     */
+    attach(stepId: string, by: PerspectiveId, artifact: Omit<Artifact, "id" | "by">): WorkflowState;
+    /**
+     * Internal artefact recorder. The public `attach` guards the credential
+     * kind; `attachCredential` enters here only after verifying a real one.
+     */
+    private recordArtifact;
+    /**
+     * Attach a real, verified switch credential to the preparation phase and
+     * bind it to the state. The workflow never trusts a caller-supplied digest
+     * string.
+     */
+    attachCredential(credential: SwitchCredential, at: Timestamp): WorkflowState;
+    /**
+     * Record an approval. The approver must own the subject and must differ
+     * from the requester.
+     */
+    approve(input: {
+        subject: ApprovalSubject;
+        by: PerspectiveId;
+        at: Timestamp;
+        requestedBy: PerspectiveId;
+        granted?: boolean;
+        note?: string;
+    }): WorkflowState;
+    hasApproval(subject: ApprovalSubject): boolean;
+    /**
+     * Advance to the next phase. Only the general manager may call this, and
+     * only when the gate is satisfied.
+     */
+    advance(by: PerspectiveId, at: Timestamp): WorkflowState;
+    /**
+     * Enter the escalation branch from any phase except archive.
+     */
+    escalate(input: {
+        by: PerspectiveId;
+        at: Timestamp;
+        type: EscalationType;
+        reason: string;
+        evidenceRefs: number;
+    }): WorkflowState;
+    /**
+     * Leave the escalation branch for the phase that asked for it.
+     */
+    resume(by: PerspectiveId, at: Timestamp): WorkflowState;
+    /**
+     * Attach the manifest reference the execution phase uses. The credential is
+     * bound only through {@link attachCredential}.
+     */
+    bind(context: {
+        manifest?: {
+            id: Id;
+            version: number;
+        };
+    }): WorkflowState;
+    block(reason: string): WorkflowState;
+    unblock(): WorkflowState;
+    terminate(at: Timestamp, reason: string): WorkflowState;
+    finish(at: Timestamp): WorkflowState;
+    hasArtifact(kind: string): boolean;
+    /**
+     * Invariant report used by checks and by the archive phase.
+     */
+    verify(): string[];
+    private archiveGateProblems;
+}