@geonosis/policy 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,375 @@
+import { a as PolicyRuleRow, b as PolicyAdapter, c as PolicyKindSpec, d as PolicyRule, e as PolicyTierSpec, f as Policy, P as PolicyQuery, g as PolicyData, h as PolicyDecision, i as PolicyScope, U as UnusableRule, J as JournalObservationEntry, j as PolicyJournal, k as PolicyConfigReader, l as PolicyRuleReader, m as PolicyReading } from './types-DzC5zTZ8.js';
+export { A as Awaitable, n as POLICY_FALLBACK, o as POLICY_INVALID_VALUE, p as PolicyJournalEntry, S as SchemaLike } from './types-DzC5zTZ8.js';
+
+/**
+ * One suite every storage adapter passes.
+ *
+ * A real Medusa module and a real drizzle table are the consumers' to run this against; what runs
+ * here is a stub, which is the point — the checks are about what an adapter must MEAN, and neither
+ * store's presence changes one of them.
+ *
+ * It answers with a report rather than an exit code: a gate that cannot say what it measured has
+ * not been shown to measure anything.
+ */
+type ConformanceCheck = {
+    detail?: string;
+    name: string;
+    passed: boolean;
+};
+type ConformanceReport = {
+    adapter: string;
+    checks: ConformanceCheck[];
+    passed: boolean;
+};
+type PolicyAdapterHarness = {
+    /** An adapter whose store holds exactly this, and a way to read what its journal received. */
+    create: (input: {
+        config?: Record<string, unknown>;
+        rows: readonly PolicyRuleRow[];
+    }) => {
+        adapter: PolicyAdapter;
+        written: () => readonly unknown[];
+    };
+    /** An adapter over a store that is DOWN. Swallowing belongs inside the adapter, not around it. */
+    createBroken: () => PolicyAdapter;
+    name: string;
+};
+declare const runPolicyAdapterConformance: (harness: PolicyAdapterHarness) => Promise<ConformanceReport>;
+
+type PolicyInput = {
+    /** What policy may constrain. A kind with no reader is an inert knob; a reader with no kind cannot be authored. */
+    kinds: readonly (PolicyKindSpec | string)[];
+    /**
+     * May the overriding tier beat a rule that does not say either way?
+     *
+     * dielime says yes (`rule.overridable !== false`), musa says no (`&& winner.overridable`).
+     * Neither is wrong for the other's business, so it is declared rather than assumed.
+     */
+    overridableByDefault?: boolean;
+    rules?: readonly PolicyRule[];
+    /** VAGUEST first — the weight of a key is derived from where it sits. */
+    scopeKeys?: readonly string[];
+    /** STRONGEST first. */
+    tiers: readonly (PolicyTierSpec | string)[];
+};
+/**
+ * Declare a policy: the authorities, the things they may constrain, the subjects they may be aimed
+ * at, and — optionally — the rules themselves.
+ *
+ * A policy with no rules is INERT. Every read falls through to the caller's own constant and says
+ * so, which is the posture the mechanism is built for: the loader is generic, the domain limits
+ * live in data, and the kernel does nothing at all until someone writes a rule.
+ */
+declare const definePolicy: (input: PolicyInput) => Policy;
+
+/**
+ * The precedence lattice — deciding which authority wins when several speak at once.
+ *
+ * A business is governed by several at a time: law, a signed agreement, its own SOP, a buyer's
+ * stated preference, the strategy currently running, an operator override typed at 6pm on a Friday.
+ * They contradict each other constantly, so "which one wins" must not be an accident of evaluation
+ * order — it is a declared ordering, and every decision carries a TRACE naming the winner and what
+ * it suppressed.
+ *
+ * Nothing in this file names a tier, a kind or a scope key. Two consumers wrote this lattice
+ * independently and disagreed on all three (dielime's strongest tier is `regulatory`, musa's is
+ * `physics`), which is why every one of them is data.
+ */
+/**
+ * The weight of a scope key, derived from where it was declared.
+ *
+ * Powers of two in declaration order, so a narrower key can never be outvoted by an accumulation of
+ * vaguer ones: an order-scoped rule beats one scoped to region + category + group together, which
+ * is the intent every time someone writes an order-scoped exception. Both consumers wrote exactly
+ * that by hand and each needed a test to catch a key that had been given no weight at all — a rule
+ * that matches but always loses. Deriving it designs the failure out.
+ */
+declare const specificityOf: (scopeKeys: readonly string[], scope: PolicyScope | undefined) => number;
+/**
+ * Does this rule reach this subject?
+ *
+ * A rule scoped on a key the query does not carry does NOT apply, and neither does one scoped on a
+ * key this build has never heard of. That is the safe direction — a rule cannot reach a subject we
+ * know nothing about — but refusing quietly is the same failure in a new coat, which is what
+ * `unsupportedScopesOf` is for.
+ */
+declare const appliesTo: (rule: PolicyRule, query: PolicyQuery, scopeKeys: readonly string[]) => boolean;
+declare const unsupportedScopesOf: (rules: readonly PolicyRule[], scopeKeys: readonly string[]) => {
+    id: string;
+    keys: string[];
+}[];
+declare const unusableRulesOf: (rules: readonly PolicyRule[], data: Pick<PolicyData, "kinds" | "tiers">) => UnusableRule[];
+declare const usableRulesOf: (rules: readonly PolicyRule[], data: Pick<PolicyData, "kinds" | "tiers">) => PolicyRule[];
+declare const unsetKindsOf: (rules: readonly PolicyRule[], kinds: readonly PolicyKindSpec[]) => string[];
+/**
+ * Resolve one kind for one subject, with the whole trace.
+ *
+ * `undefined` when no rule speaks — silence is a legitimate answer and the caller's own default
+ * takes over. Never a thrown error: a missing rule is the normal state of most subjects, and of
+ * every subject in a build nobody has written a policy for yet.
+ */
+declare const resolveConstraint: <V = unknown>(data: PolicyData, kind: string, query?: PolicyQuery, rules?: readonly PolicyRule[]) => PolicyDecision<V> | undefined;
+
+/**
+ * The learning loop — a business improves from its own operations, visibly, versioned and
+ * reversibly.
+ *
+ * Shaped after ACE (Generator / Reflector / Curator): the playbook EVOLVES by increments rather
+ * than rewrites, which is what stops accumulated context from collapsing as it grows.
+ *
+ *   observeJournal  deterministic signal extraction — no model, fully testable. The strongest
+ *                   signals are BEHAVIOURAL: a human reversing an automated decision is unambiguous
+ *                   feedback in a way a survey never is.
+ *   reflect         folds repeats into one candidate each. An agent may propose candidates too;
+ *                   they enter through this same gate.
+ *   curate          merges by stable id, ACCUMULATING evidence instead of overwriting statements.
+ *   promote         evidence-gated. demote is always available and always recorded — auditable
+ *                   unlearning is the point.
+ *
+ * The safety rail is the lattice: an active learning becomes a rule at the ADVISORY tier, which
+ * can only ever fill silence. The loop can suggest; it can never quietly change what a business does.
+ */
+type LearningKind = 
+/** A working practice worth repeating. */
+'heuristic'
+/** A trap worth naming, so the next session starts knowing it. */
+ | 'pitfall'
+/** Policy and the people running the business disagree, repeatedly. */
+ | 'rule-friction'
+/** The same sequence keeps being run by hand — name it. */
+ | 'macro'
+/** A knob that exists but nothing sets, so a hardcoded default rules instead. */
+ | 'unset-policy';
+type LearningStatus = 'active' | 'candidate' | 'demoted';
+type LearningEvidence = {
+    /** Ids of the journal entries that support it. */
+    journalRefs: string[];
+    /** Measured effect, when there is one. */
+    metric?: {
+        delta: number;
+        name: string;
+    };
+    observations: number;
+    updatedAt: string;
+};
+type Learning = {
+    demotedReason?: string;
+    evidence: LearningEvidence;
+    /** Stable key — curation merges on this, so evidence accumulates. */
+    id: string;
+    kind: LearningKind;
+    scope?: PolicyScope;
+    /** What was learned, in words a human can audit and edit. */
+    statement: string;
+    status: LearningStatus;
+    /** The advisory constraint this implies, if any. */
+    suggests?: {
+        kind: string;
+        value: unknown;
+    };
+};
+type Playbook = {
+    entries: Learning[];
+    version: number;
+};
+type Observation = {
+    id: string;
+    journalRefs: string[];
+    kind: LearningKind;
+    scope?: PolicyScope;
+    statement: string;
+    suggests?: {
+        kind: string;
+        value: unknown;
+    };
+};
+declare const emptyPlaybook: () => Playbook;
+/** Repeated evidence, not one lucky quarter. */
+declare const DEFAULT_MIN_OBSERVATIONS = 3;
+declare class LearningError extends Error {
+    readonly code: 'INSUFFICIENT_EVIDENCE' | 'UNKNOWN_LEARNING';
+    constructor(code: 'INSUFFICIENT_EVIDENCE' | 'UNKNOWN_LEARNING', message: string);
+}
+type ObserveOptions = {
+    /** How few repeats of one operation are still a one-off. */
+    minRepeatsForMacro?: number;
+    /** The prefix a refusal carries, so friction is countable per rule. That word is a repo's own. */
+    refusalPrefix?: string;
+    /** What a human doing the undoing tends to call it. */
+    reversalVerbs?: RegExp;
+};
+/**
+ * The deterministic signals in a journal. Only behaviour that actually happened counts; nothing is
+ * inferred from intent alone.
+ */
+declare const observeJournal: (entries: readonly JournalObservationEntry[], options?: ObserveOptions) => Observation[];
+/** Fold repeats into one candidate each — the statistical reflector. */
+declare const reflect: (observations: readonly Observation[], now?: Date) => Learning[];
+/**
+ * Merge candidates into the playbook. Evidence ACCUMULATES, and a statement is only refreshed while
+ * the entry is still under review — an active learning's wording is stable, which is what makes the
+ * playbook readable a year later.
+ */
+declare const curate: (playbook: Playbook, candidates: readonly Learning[]) => Playbook;
+declare const promote: (playbook: Playbook, id: string, options?: {
+    metric?: {
+        delta: number;
+        name: string;
+    };
+    minObservations?: number;
+}) => Playbook;
+/** Demotion is always available and always recorded — auditable unlearning. */
+declare const demote: (playbook: Playbook, id: string, reason: string) => Playbook;
+/**
+ * Active learnings that imply a constraint, as rules at the tier the policy calls advisory.
+ *
+ * dielime writes `tier: 'learned'` into this function. Here the tier is read off the lattice,
+ * because a policy that declares none has nowhere safe to put a suggestion — and quietly choosing
+ * one would hand a suggestion the authority of an SOP.
+ */
+declare const playbookRules: (policy: Policy, playbook: Playbook) => PolicyRule[];
+/** The playbook as agent-readable guidance — a delta on top of a built prompt, never a replacement. */
+declare const playbookGuidance: (playbook: Playbook) => string;
+
+/** One journal row derived from something that happened. */
+type DomainJournalRow = {
+    actor_id: null | string;
+    actor_kind: 'system' | 'user';
+    event_name: string;
+    op: string;
+    subject: string;
+};
+type JournalRowOptions = {
+    /** Where this build puts the human who caused it, when there is one. */
+    actorKeys?: readonly string[];
+    /** Where this build puts the id of the thing an event is about. */
+    subjectKeys: readonly string[];
+};
+/**
+ * The journal row for one domain event, or `null` when there is nothing countable to say.
+ *
+ * The learning loop reads four signals: a human reversing an automated decision, repeated refusals
+ * of the same rule, readers falling back to their own defaults, and the same operation run over and
+ * over. A reader journals its own fallbacks, so the third arrives on its own — the other three are
+ * computed from things that HAPPENED, and without this they are computed over an empty table.
+ *
+ * The keys are the caller's, with no default: which field carries the id of the thing an event is
+ * about is a fact about one system, and guessing would be quietly wrong rather than loudly absent.
+ */
+declare const journalRowForEvent: (eventName: string, data: unknown, options: JournalRowOptions) => DomainJournalRow | null;
+
+/**
+ * The policy as prose, generated beside the data it renders.
+ *
+ * musa checks in `policy/policy.json` and a `POLICY.md` written from it on every change, and the
+ * argument for generating rather than writing it is in that file's own history: two of its sections
+ * were prose, and both had gone stale and were telling agents the opposite of what the code did. A
+ * markdown that has to be remembered separately drifts, and a drifted one is worse than none — it
+ * reads authoritative while the engine enforces something else.
+ *
+ * So every count, every precedence sentence and every honesty report below is DERIVED.
+ */
+type PolicyMarkdownOptions = {
+    generator?: string;
+    playbook?: Playbook;
+    rules?: readonly PolicyRule[];
+    /** What a reader should edit instead of this file. */
+    source?: string;
+    title?: string;
+};
+declare const generatePolicyMarkdown: (policy: Policy, options?: PolicyMarkdownOptions) => string;
+type DescribePolicyOptions = {
+    /** Instructions ride in EVERY context, so this stays bounded. */
+    maxRules?: number;
+    playbook?: Playbook;
+    rules?: readonly PolicyRule[];
+};
+/**
+ * The same policy, bounded, for the channel an agent is handed when it connects.
+ *
+ * Persisting policy is only half the job: an agent that has to discover the rules by tripping over
+ * them will trip over them in front of a customer.
+ */
+declare const describePolicy: (policy: Policy, options?: DescribePolicyOptions) => string;
+
+type ReadPolicyOptions<V> = {
+    config?: PolicyConfigReader;
+    /** The caller's own constant — the floor, and the type of the answer. */
+    fallback: V;
+    journal?: PolicyJournal;
+    /** A named operation, so repeats become countable per operation rather than per request. */
+    op?: string;
+    rule?: PolicyRuleReader;
+    /** Opt out of recording. Only for a caller that runs per request inside a loop. */
+    silent?: boolean;
+    /** What the decision is about — an order id, a company id. */
+    subject?: string;
+};
+/**
+ * Read one constraint, with the caller's own default as the floor.
+ *
+ * This is what a reader calls instead of reaching for a hardcoded constant. It answers with the
+ * resolved value when policy speaks, the admin-set value when it does not, and the caller's own
+ * constant when nobody has said anything — and, the part that matters, it RECORDS that last case,
+ * so "nothing sets this" becomes a countable signal rather than a silence indistinguishable from
+ * working.
+ *
+ * The resolution order is authored rule → config row → constant. A rule wins because it carries an
+ * authority, a subject and a reason where a config row carries only a value; a config row beats the
+ * constant because a value an admin actually typed must beat one a developer compiled in, or the
+ * settings screen is a screen of knobs nothing reads.
+ */
+declare const readPolicy: <V>(policy: Policy, kind: string, query: PolicyQuery | undefined, options: ReadPolicyOptions<V>) => Promise<PolicyReading<V>>;
+type PolicyOrDefaultInput<V> = {
+    fallback: V;
+    journal?: PolicyJournal;
+    kind: string;
+    op: string;
+    subject?: string;
+    value: V;
+};
+/**
+ * Apply a resolved value, falling back to the caller's own default when it turns out to be
+ * unusable.
+ *
+ * A validator that refuses a zero-day expiry or a zero-hour SLA is right to. But a number an admin
+ * mistypes would then throw inside the work it was informing, and every one of those operations
+ * would fail until somebody noticed — the customer paying for a misconfiguration. An unusable value
+ * is a gap that arrived through a different door, so it is treated like every other gap: recorded
+ * once per boot, and the default takes over while the mistake stays visible.
+ *
+ * A default that ALSO fails still throws. That is a bug in our own code rather than a
+ * misconfiguration, and swallowing it would leave the caller with no value at all.
+ */
+declare const policyOrDefault: <T, V>(policy: Policy, input: PolicyOrDefaultInput<V>, apply: (value: V) => T) => Promise<T>;
+
+/**
+ * A stored row, as a rule the lattice can use.
+ *
+ * This is the one part of a storage adapter that is not the store's own vocabulary, so it lives
+ * once: two adapters that each did their own mapping would drift on what `overridable: true` means,
+ * or on whether a null scope is a scope of nothing.
+ */
+declare const toPolicyRule: (row: PolicyRuleRow) => PolicyRule;
+/** The rules still in force. A retired row stays readable — it just stops deciding. */
+declare const toPolicyRules: (rows: readonly PolicyRuleRow[]) => PolicyRule[];
+
+/** A rule as a store hands it back: the kernel's shape, plus whether it is still in force. */
+type ExistingPolicyRule = PolicyRule & {
+    status?: string;
+};
+/**
+ * Which seed rules to author, given what is already there. Idempotent by ID and by COVERAGE.
+ *
+ * The coverage half is the one that was learned the hard way: a first seeding run produced two
+ * active rules for one constraint with identical scope and value — the seed's, and one an admin had
+ * authored by hand two days earlier. Same effect, two keys, and a conflict the lattice reports and
+ * a human has to unpick.
+ *
+ * A seed provides DEFAULTS. If the business has already said something about a constraint at the
+ * same scope, it has spoken, and the seed's opinion is not wanted. A RETIRED rule is not a current
+ * opinion, so it does not block.
+ */
+declare const rulesToSeed: <T extends PolicyRule>(seed: readonly T[], existing: readonly ExistingPolicyRule[]) => T[];
+
+export { type ConformanceCheck, type ConformanceReport, DEFAULT_MIN_OBSERVATIONS, type DescribePolicyOptions, type DomainJournalRow, type ExistingPolicyRule, JournalObservationEntry, type JournalRowOptions, type Learning, LearningError, type LearningEvidence, type LearningKind, type LearningStatus, type Observation, type ObserveOptions, type Playbook, Policy, PolicyAdapter, type PolicyAdapterHarness, PolicyConfigReader, PolicyData, PolicyDecision, type PolicyInput, PolicyJournal, PolicyKindSpec, type PolicyMarkdownOptions, type PolicyOrDefaultInput, PolicyQuery, PolicyReading, PolicyRule, PolicyRuleReader, PolicyRuleRow, PolicyScope, PolicyTierSpec, type ReadPolicyOptions, UnusableRule, appliesTo, curate, definePolicy, demote, describePolicy, emptyPlaybook, generatePolicyMarkdown, journalRowForEvent, observeJournal, playbookGuidance, playbookRules, policyOrDefault, promote, readPolicy, reflect, resolveConstraint, rulesToSeed, runPolicyAdapterConformance, specificityOf, toPolicyRule, toPolicyRules, unsetKindsOf, unsupportedScopesOf, unusableRulesOf, usableRulesOf };