attention-manifest-protocol 0.4.0 → 0.4.2

package/lib/governance/matrix.js

@@ -0,0 +1,365 @@
+import { FloorRank, FloorTier, GovernanceError, ModeIds, ScenarioIds, SensitivityRank } from "./types.js";
+/**
+ * Default weights, copied exactly from spec section 9.1. Each row sums to 1.
+ */
+export const DefaultModeWeights = {
+    chat: { affect: 0.5, think: 0.2, diverge: 0.2, converge: 0.1 },
+    writing: { affect: 0.1, think: 0.2, diverge: 0.5, converge: 0.2 },
+    office: { affect: 0.1, think: 0.3, diverge: 0.1, converge: 0.5 },
+    research: { affect: 0.05, think: 0.4, diverge: 0.4, converge: 0.15 },
+    engineering: { affect: 0.05, think: 0.35, diverge: 0.1, converge: 0.5 },
+};
+/**
+ * Evidence floors per scenario and mode (spec section 9.4), translated from
+ * the description's T1/T2/T3 wording into the governance F1/F2/F3 order.
+ */
+export const EvidenceFloorTable = {
+    chat: { affect: "F3", think: "F3", diverge: "F3", converge: "F3" },
+    writing: { affect: "F3", think: "F2", diverge: "F3", converge: "F2" },
+    office: { affect: "F2", think: "F2", diverge: "F2", converge: "F2" },
+    research: { affect: "F2", think: "F1", diverge: "F2", converge: "F2" },
+    engineering: { affect: "F2", think: "F1", diverge: "F2", converge: "F1" },
+};
+/**
+ * Frame cadence for re-evaluating ignored items (spec section 9.5).
+ */
+export const RevisitIntervalTable = {
+    chat: { affect: 10, think: 5, diverge: 8, converge: 10 },
+    writing: { affect: 8, think: 5, diverge: 2, converge: 4 },
+    office: { affect: 8, think: 4, diverge: 6, converge: 4 },
+    research: { affect: 10, think: 3, diverge: 2, converge: 4 },
+    engineering: { affect: 10, think: 3, diverge: 4, converge: 2 },
+};
+/**
+ * Budget elasticity per scenario and mode (spec section 9.6).
+ */
+export const ElasticityTable = {
+    chat: { affect: "low", think: "low", diverge: "medium", converge: "low" },
+    writing: { affect: "low", think: "medium", diverge: "high", converge: "medium" },
+    office: { affect: "low", think: "medium", diverge: "low", converge: "medium" },
+    research: { affect: "low", think: "high", diverge: "high", converge: "medium" },
+    engineering: { affect: "low", think: "high", diverge: "medium", converge: "high" },
+};
+/**
+ * Escalation-trigger sensitivity (spec section 9.7).
+ */
+export const SensitivityTable = {
+    chat: { affect: "very-low", think: "low", diverge: "low", converge: "low" },
+    writing: { affect: "low", think: "medium", diverge: "low", converge: "medium" },
+    office: { affect: "low", think: "medium", diverge: "medium", converge: "medium" },
+    research: { affect: "medium", think: "high", diverge: "medium", converge: "high" },
+    engineering: { affect: "medium", think: "high", diverge: "medium", converge: "high" },
+};
+/**
+ * Which perspectives a scenario activates by default.
+ */
+export const PerspectiveActivationTable = {
+    chat: {
+        default: ["customer-service"],
+        onDemand: ["marketing"],
+        dormant: ["strategy", "technology", "supervisory", "board"],
+        note: "Market research is rare in chat and stays dormant most of the time.",
+    },
+    writing: {
+        default: ["customer-service", "writing"],
+        onDemand: ["marketing", "strategy"],
+        dormant: ["technology", "supervisory"],
+    },
+    office: {
+        default: ["customer-service", "operations"],
+        onDemand: ["finance", "legal"],
+        dormant: ["strategy", "technology", "marketing"],
+    },
+    research: {
+        default: ["customer-service", "strategy", "marketing"],
+        onDemand: ["technology", "supervisory"],
+        dormant: ["operations"],
+    },
+    engineering: {
+        default: ["customer-service", "technology", "operations"],
+        onDemand: ["legal", "supervisory", "strategy"],
+        dormant: ["marketing"],
+        note: "Marketing is dormant but can be pulled in for user-facing impact review.",
+    },
+};
+export const ModeAdjustments = {
+    affect: {
+        focusBias: "narrow",
+        focusDelta: 0,
+        revisitMultiplier: 1,
+        elasticityBias: 0,
+        gateBias: -1,
+        note: "Focus on emotional signals and relationship maintenance; loosen the gate, keep behaviour conservative.",
+    },
+    think: {
+        focusBias: "neutral",
+        focusDelta: 0,
+        revisitMultiplier: 1,
+        elasticityBias: 0,
+        gateBias: 1,
+        note: "Focus on the evidence chain and causal structure; raise the check frequency.",
+    },
+    diverge: {
+        focusBias: "broad",
+        focusDelta: 2,
+        revisitMultiplier: 0.5,
+        elasticityBias: 1,
+        gateBias: 0,
+        note: "Widen the focus set, revisit ignored items twice as often, allow more budget slack.",
+    },
+    converge: {
+        focusBias: "narrow",
+        focusDelta: -2,
+        revisitMultiplier: 1.5,
+        elasticityBias: -1,
+        gateBias: 0,
+        note: "Shrink the focus to the candidate set, tighten the budget, make escalation triggers more sensitive.",
+    },
+};
+const ElasticityRank = { low: 0, medium: 1, high: 2 };
+const GateStrictnessByScenario = {
+    chat: "loose",
+    writing: "medium",
+    office: "medium",
+    research: "medium-strict",
+    engineering: "strict",
+};
+const ActiveThreshold = 0.15;
+/**
+ * Validate a scenario id at runtime; unknown values fail closed.
+ */
+export const requireScenario = (value) => {
+    if (!ScenarioIds.includes(value)) {
+        throw new GovernanceError("invalid-scenario", `${value} is not a canonical scenario`);
+    }
+    return value;
+};
+/**
+ * Normalize a partial weight vector onto the mode simplex.
+ *
+ * Negative, non-finite and all-zero vectors are rejected: a manifest without a
+ * mode is not a valid manifest.
+ */
+export const normalizeModeWeights = (input) => {
+    const result = { affect: 0, think: 0, diverge: 0, converge: 0 };
+    let total = 0;
+    for (let index = 0; index < ModeIds.length; index += 1) {
+        const mode = ModeIds[index];
+        const raw = input[mode] ?? 0;
+        if (!Number.isFinite(raw) || raw < 0) {
+            throw new GovernanceError("invalid-mode-weights", `${mode} must be a finite non-negative number`);
+        }
+        result[mode] = raw;
+        total += raw;
+    }
+    if (total <= 0) {
+        throw new GovernanceError("invalid-mode-weights", "at least one mode weight must be positive");
+    }
+    for (let index = 0; index < ModeIds.length; index += 1) {
+        const mode = ModeIds[index];
+        result[mode] = result[mode] / total;
+    }
+    return result;
+};
+/**
+ * Modes sorted by weight, descending; ties keep the canonical order.
+ */
+export const rankModes = (weights) => {
+    const ranked = [...ModeIds];
+    ranked.sort((left, right) => weights[right] - weights[left] || ModeIds.indexOf(left) - ModeIds.indexOf(right));
+    return ranked;
+};
+export const dominantMode = (weights) => rankModes(weights)[0];
+/**
+ * Modes receiving at least 15% of attention. One mode always qualifies
+ * because the vector sums to 1.
+ */
+export const activeModes = (weights, threshold = ActiveThreshold) => {
+    const active = ModeIds.filter((mode) => weights[mode] >= threshold);
+    return active.length === 0 ? [dominantMode(weights)] : active;
+};
+/**
+ * Strictest floor across the active modes: a mixed task inherits the hardest
+ * evidence demand, never the easiest.
+ */
+export const evidenceFloorFor = (scenario, weights) => {
+    const modes = activeModes(weights);
+    let strictest = "F3";
+    for (let index = 0; index < modes.length; index += 1) {
+        const floor = EvidenceFloorTable[scenario][modes[index]];
+        if (FloorRank[floor] < FloorRank[strictest]) {
+            strictest = floor;
+        }
+    }
+    return strictest;
+};
+/**
+ * Revisit cadence for ignored items: the most frequent cadence among active
+ * modes, so a divergence-heavy mix does not let ignored items go stale.
+ */
+export const revisitIntervalFor = (scenario, weights) => {
+    const modes = activeModes(weights);
+    let interval = Number.POSITIVE_INFINITY;
+    for (let index = 0; index < modes.length; index += 1) {
+        interval = Math.min(interval, RevisitIntervalTable[scenario][modes[index]]);
+    }
+    return Math.max(2, Number.isFinite(interval) ? interval : 10);
+};
+/**
+ * Budget elasticity: the most restrictive active mode wins, unless a mode
+ * explicitly raises it and no other mode forbids it. Safety-first by design.
+ */
+export const elasticityFor = (scenario, weights) => {
+    const modes = activeModes(weights);
+    let elasticity = "high";
+    for (let index = 0; index < modes.length; index += 1) {
+        const candidate = ElasticityTable[scenario][modes[index]];
+        if (ElasticityRank[candidate] < ElasticityRank[elasticity]) {
+            elasticity = candidate;
+        }
+    }
+    return elasticity;
+};
+/**
+ * Escalation sensitivity: the most sensitive active mode wins.
+ */
+export const sensitivityFor = (scenario, weights) => {
+    const modes = activeModes(weights);
+    let sensitivity = "very-low";
+    for (let index = 0; index < modes.length; index += 1) {
+        const candidate = SensitivityTable[scenario][modes[index]];
+        if (SensitivityRank[candidate] > SensitivityRank[sensitivity]) {
+            sensitivity = candidate;
+        }
+    }
+    return sensitivity;
+};
+/**
+ * Focus-set size: divergence widens it, convergence shrinks it (spec 9.2).
+ */
+export const focusLimitFor = (weights) => {
+    const raw = 3 + Math.round(4 * weights.diverge) - Math.round(2 * weights.converge);
+    return Math.max(1, Math.min(9, raw));
+};
+export const gateStrictnessFor = (scenario) => GateStrictnessByScenario[scenario];
+export const resolveScenarioModes = (scenario, override) => {
+    const checked = requireScenario(scenario);
+    const modes = override === (void 0) ? { ...DefaultModeWeights[checked] } : normalizeModeWeights(override);
+    const ranked = rankModes(modes);
+    const floor = evidenceFloorFor(checked, modes);
+    const plan = {
+        scenario: checked,
+        modes,
+        dominant: ranked[0],
+        secondary: ranked[1],
+        active: activeModes(modes),
+        evidenceFloor: floor,
+        requiredTier: FloorTier[floor],
+        revisitEvery: revisitIntervalFor(checked, modes),
+        elasticity: elasticityFor(checked, modes),
+        sensitivity: sensitivityFor(checked, modes),
+        gateStrictness: gateStrictnessFor(checked),
+        focusLimit: focusLimitFor(modes),
+        rationale: `${checked} -> ${ranked
+            .slice(0, 2)
+            .map((mode) => `${mode} ${modes[mode].toFixed(2)}`)
+            .join(" + ")}; floor ${floor} (${FloorTier[floor]}), revisit every ${revisitIntervalFor(checked, modes)} frames, elasticity ${elasticityFor(checked, modes)}`,
+    };
+    return plan;
+};
+/**
+ * Active-mode adjustments, used by the manifest deriver to explain itself.
+ */
+export const modeAdjustments = (weights) => {
+    const active = activeModes(weights);
+    return active.map((mode) => ({ mode, weight: weights[mode], adjustment: ModeAdjustments[mode] }));
+};
+/**
+ * Largest single-dimension drift between two weight vectors.
+ */
+export const modeDrift = (from, to) => {
+    let drift = 0;
+    for (let index = 0; index < ModeIds.length; index += 1) {
+        const mode = ModeIds[index];
+        drift = Math.max(drift, Math.abs(from[mode] - to[mode]));
+    }
+    return drift;
+};
+/**
+ * Mode changes above 0.15 need the general manager's approval (spec 9.3).
+ */
+export const driftRequiresApproval = (from, to) => modeDrift(from, to) > 0.15 + 1e-9;
+/**
+ * A scenario change always re-derives the manifest; it is never a patch.
+ */
+export const scenarioChangeRequiresRederive = (from, to) => from !== to;
+/**
+ * Bridge: the five canonical scenarios all exist as legacy scenario kinds.
+ */
+export const legacyScenarioMix = (scenario) => {
+    const mix = {};
+    mix[scenario] = 1;
+    return mix;
+};
+/**
+ * Bridge: map a legacy eight-kind mix onto its dominant canonical scenario.
+ */
+export const canonicalScenarioOf = (mix) => {
+    const legacy = mix;
+    const order = ["chat", "writing", "office", "collaboration", "investigation", "research", "engineering", "iteration"];
+    let best = "chat";
+    let bestWeight = 0;
+    for (let index = 0; index < order.length; index += 1) {
+        const kind = order[index];
+        const weight = legacy[kind] ?? 0;
+        if (weight > bestWeight) {
+            best = kind;
+            bestWeight = weight;
+        }
+    }
+    if (bestWeight <= 0) {
+        throw new GovernanceError("invalid-scenario", "a scenario mix must contain at least one positive weight");
+    }
+    return scenarioOfLegacy(best);
+};
+/**
+ * Bridge: collapse the three scenario kinds that have no canonical peer.
+ */
+export const scenarioOfLegacy = (kind) => {
+    switch (kind) {
+        case "collaboration":
+            return "office";
+        case "investigation":
+            return "research";
+        case "iteration":
+            return "engineering";
+        default:
+            return kind;
+    }
+};
+/**
+ * Bridge: the legacy interaction vocabulary uses `inspire` where governance
+ * says `diverge`.
+ */
+export const legacyInteractionMix = (weights) => {
+    const mapping = { affect: "affect", think: "think", diverge: "inspire", converge: "converge" };
+    const mix = {};
+    for (let index = 0; index < ModeIds.length; index += 1) {
+        const mode = ModeIds[index];
+        mix[mapping[mode]] = weights[mode];
+    }
+    return mix;
+};
+/**
+ * Bridge: derive governance modes from a legacy interaction mix. Missing
+ * `orchestrate` weight is folded into `converge`, the planning mode.
+ */
+export const modesFromLegacyInteraction = (mix) => {
+    const orchestrate = mix.orchestrate ?? 0;
+    return normalizeModeWeights({
+        affect: mix.affect ?? 0,
+        think: mix.think ?? 0,
+        diverge: mix.inspire ?? 0,
+        converge: (mix.converge ?? 0) + orchestrate,
+    });
+};

package/lib/governance/perspectives.d.ts

@@ -0,0 +1,98 @@
+/**
+ * The perspective registry (spec section 4, section 12.1).
+ *
+ * A perspective is a governed attention stance with a manifest, a budget and
+ * an approval role. The registry is deliberately data-only: the manifest,
+ * credential and workflow modules read it instead of hard-coding a role name.
+ *
+ * Finance, human resources and administration are rule modules or
+ * infrastructure, not switchable perspectives; they remain addressable so
+ * their approval and accounting duties can be expressed.
+ */
+import type { Activation, ApprovalSubject, PerspectiveId, PerspectiveLayer, ScenarioId } from "./types.js";
+import type { ScenarioPerspectives } from "./matrix.js";
+/**
+ * One registry row.
+ */
+export interface PerspectiveDefinition {
+    id: PerspectiveId;
+    labelZh: string;
+    labelEn: string;
+    layer: PerspectiveLayer;
+    /**
+     * What this perspective attends to when its manifest is loaded.
+     */
+    focus: string[];
+    /**
+     * Activation cadence in prose; the scenario table decides per task.
+     */
+    frequency: string;
+    switchable: boolean;
+    /**
+     * May this perspective be the target of a same-level switch credential?
+     * Strategic perspectives require the escalation path instead.
+     */
+    directSwitch: boolean;
+    /**
+     * May this perspective counter-sign a switch credential?
+     */
+    signsCredentials: boolean;
+    /**
+     * Approval subjects this perspective owns.
+     */
+    approve: ApprovalSubject[];
+    /**
+     * True for the independent evidence audit path.
+     */
+    independentAudit: boolean;
+}
+/**
+ * The canonical registry. Order follows the governance template.
+ */
+export declare const PerspectiveRegistry: Record<PerspectiveId, PerspectiveDefinition>;
+/**
+ * The standing perspectives of section 12.1 (the writing desk is a
+ * scenario-specific view and is excluded from the standing count).
+ */
+export declare const StandingPerspectives: readonly PerspectiveId[];
+/**
+ * Look up a perspective, failing closed for unknown ids.
+ */
+export declare const perspective: (id: string) => PerspectiveDefinition;
+export declare const isKnownPerspective: (id: string) => id is PerspectiveId;
+/**
+ * Rule modules and infrastructure are not switchable perspectives.
+ */
+export declare const isRuleModule: (id: PerspectiveId) => boolean;
+/**
+ * Strategic perspectives are reached through escalation, never a same-level
+ * switch credential.
+ */
+export declare const requiresEscalation: (id: PerspectiveId) => boolean;
+export declare const canApprove: (id: PerspectiveId, subject: ApprovalSubject) => boolean;
+/**
+ * Who may approve a subject, in registry order (used for routing refusals).
+ */
+export declare const approversOf: (subject: ApprovalSubject) => PerspectiveId[];
+/**
+ * A same-level switch credential is issued by the general manager to a
+ * non-strategic, directly switchable perspective.
+ */
+export declare const canIssueCredential: (from: PerspectiveId, to: PerspectiveId) => boolean;
+/**
+ * Which strategic target an escalation type may reach.
+ */
+export declare const escalationTarget: (type: "audit" | "strategy" | "final" | "compliance") => PerspectiveId;
+/**
+ * Scenario activation for one perspective (spec section 9.8).
+ */
+export declare const activationFor: (id: PerspectiveId, scenario: ScenarioId) => Activation;
+/**
+ * The activation plan for a scenario, with copies so callers cannot mutate the
+ * table.
+ */
+export declare const perspectivesForScenario: (scenario: ScenarioId) => ScenarioPerspectives;
+/**
+ * Registry self-check; used by checks and on first import in development.
+ */
+export declare const validatePerspectiveRegistry: () => string[];