@owlmeans/viable-common 0.0.4

package/build/metadata/types.d.ts

@@ -0,0 +1,286 @@
+import type { SpecCategory } from '../ba/consts.js';
+export interface MetadataFile<T extends Record<string, unknown> = Record<string, unknown>> {
+    path: string;
+    data: T;
+    body: string;
+}
+export interface MetadataWriteInput<T extends Record<string, unknown> = Record<string, unknown>> {
+    data?: Partial<T>;
+    body: string;
+}
+export declare enum MetadataKind {
+    Project = "project",
+    Story = "story",
+    Source = "source",
+    History = "history"
+}
+export declare enum MetadataListKind {
+    Stories = "stories",
+    Meta = "meta",
+    All = "all"
+}
+/**
+ * Identifies a single metadata document to read:
+ * - Project:  kind=Project, no ref/category needed
+ * - Story:    kind=Story,   ref=story-code
+ * - Source:   kind=Source,  ref=source-path, category=SpecCategory
+ */
+export interface MetadataRef {
+    kind: MetadataKind;
+    ref?: string;
+    category?: SpecCategory;
+}
+/**
+ * Identifies a list of metadata documents to enumerate:
+ * - Stories: kind=Stories  → returns story codes
+ * - Meta:    kind=Meta     → returns co-located *.spec/.ux/.ui.md paths;
+ *                            category narrows to one suffix
+ */
+export interface MetadataListRef {
+    kind: MetadataListKind;
+    category?: SpecCategory;
+}
+/** Frontmatter for docs/project.md */
+export interface ProjectMeta extends Record<string, unknown> {
+    name: string;
+    alias: string;
+    /**
+     * The language every piece of generated UI text is written in — labels, headings, empty
+     * states, validation messages, i18n values.
+     *
+     * Recorded on the project rather than asked per pass, because a screen scaffolded in one
+     * language and extended in another is a mixed interface that nothing reports: the code
+     * compiles, the tests pass, and only a reader of the running app can see it. An IETF tag
+     * (`en`, `pl`, `pt-BR`).
+     */
+    language: string;
+}
+/**
+ * Frontmatter for `.agents/memory/history.md`.
+ *
+ * `lastEvent` is written verbatim on every record and rendered as the first line of the history
+ * block. That is what makes "the summary always names the most recent event" a property of the
+ * file rather than a hope about the model that folded it.
+ */
+export interface HistoryMeta extends Record<string, unknown> {
+    version: number;
+    updatedAt: string;
+    lastEvent: string;
+}
+/** Frontmatter for docs/entities/<name>.md */
+export interface EntityMeta extends Record<string, unknown> {
+    name: string;
+    attributes: Array<{
+        name: string;
+        description: string;
+    }>;
+}
+/** Ref to a screen inside a docs/stories/<code>.md index */
+export interface StoryScreenRef {
+    name: string;
+    path: string;
+    /** Top-menu group this screen renders under. A label, never a URL segment. */
+    section?: string;
+    components: StoryComponentRef[];
+}
+/** Ref to a component inside a docs/stories/<code>.md index */
+export interface StoryComponentRef {
+    name: string;
+    path: string;
+}
+/** Frontmatter for docs/stories/<code>.md */
+export interface StoryMeta extends Record<string, unknown> {
+    code: string;
+    status: string;
+    primary: boolean;
+    /** The audience this story serves; its screens live under that area's entrypoint. */
+    area: string;
+    /**
+     * The top-menu section the scaffold reserved for this story, inside its area.
+     *
+     * Assigned before any of the story's code exists, so that the stub screen drawn at
+     * initialization and the real screen developed later land in the SAME menu group — a story
+     * that moves section when it is implemented leaves its own dashboard behind.
+     */
+    section?: string;
+    entity: string;
+    entities: string[];
+    screens: StoryScreenRef[];
+    transitions: Array<{
+        from: string;
+        to: string;
+        initiator: string;
+        action: string;
+        type: string;
+    }>;
+}
+/** Frontmatter for co-located <screen>.spec.md */
+export interface ScreenMeta extends Record<string, unknown> {
+    name: string;
+    stories: string[];
+    area?: string;
+    section?: string;
+    components: string[];
+}
+/** Frontmatter for co-located <component>.spec.md */
+export interface ComponentMeta extends Record<string, unknown> {
+    name: string;
+    stories: string[];
+    entities: string[];
+}
+/**
+ * Payload the agent passes to store.writeStory — all data the developer
+ * collected during one develop run.
+ */
+export interface StoryWriteInput {
+    code: string;
+    narrative: string;
+    status: string;
+    primary: boolean;
+    /** Carried through a develop run so the rewrite does not drop the scaffold's assignment. */
+    section?: string;
+    /** Likewise the reserved screen name. */
+    screen?: string;
+    userStory: import('../ba/types.js').UserStory;
+    /** Each entry maps a StoryScreen to its source path in the target project */
+    screenPaths: Record<string, string>;
+    /** Each entry maps a StoryComponent to its source path in the target project */
+    componentPaths: Record<string, string>;
+    transitions: Array<{
+        from: string;
+        to: string;
+        initiator: string;
+        action: string;
+        type: string;
+    }>;
+}
+/**
+ * What a registry entry names.
+ *
+ * One entry per artifact the pipeline can generate, so that "where does this live" and "what is
+ * it called" have exactly one answer for the whole life of the project.
+ */
+export declare enum RegistryKind {
+    /** The single directory segment an entity owns across models/, resources/ and backend models/ */
+    EntityDir = "entity-dir",
+    ModelType = "model-type",
+    Resource = "resource",
+    BackendModel = "backend-model",
+    ApiHandlers = "api-handlers",
+    Service = "service",
+    Layout = "layout",
+    Screen = "screen",
+    Component = "component",
+    ViewModel = "view-model",
+    State = "state",
+    /** Alias-only entry for one endpoint — carries no source path of its own */
+    ApiEntrypoint = "api-entrypoint"
+}
+/**
+ * One allocated name.
+ *
+ * `name` is the lookup key — the entity name for entity-scoped kinds, the definition otherwise.
+ * Everything else is what generated code must use verbatim: a coder that writes a different
+ * directory, and a fixer that renames a reference instead of declaring the missing thing, are the
+ * two failure modes this record exists to make impossible.
+ */
+export interface RegistryAllocation extends Record<string, unknown> {
+    kind: RegistryKind;
+    name: string;
+    /** Repo-relative source path; empty for alias-only kinds */
+    path: string;
+    /** Resource alias (also the physical table name) or entrypoint alias */
+    alias?: string;
+    /** Dotted `app.*` reference the generated code uses to reach the alias */
+    appRef?: string;
+    /** Exported symbol — screen/layout/component/handler */
+    symbol?: string;
+    /**
+     * The FULL assembled route, recorded when an entrypoint is declared — area prefix included.
+     *
+     * The declaration that produces it carries only the tail, because a child path is appended to
+     * its parent's; `areaSegment` is what shortens this value when a declaration is written back.
+     */
+    url?: string;
+    /** Parent entrypoint alias — for a screen that is its AREA, for an endpoint its group */
+    parent?: string;
+    /** The area a screen belongs to — one of the four {@link ProjectArea} values. */
+    area?: string;
+    /** Top-menu group of a screen. A label, never a URL segment. */
+    section?: string;
+    /**
+     * A SCAFFOLD placeholder — drawn at initialization, replaced or deleted later.
+     *
+     * The flag is what makes cleanup deterministic instead of a judgement call. It survives until
+     * either the story behind the artifact is implemented (the file is rewritten in place and the
+     * flag is cleared) or something else edits the file, which clears the flag as well: whoever
+     * edited it meant it, so nothing may delete it afterwards.
+     */
+    stub?: boolean;
+    /**
+     * SHA-256 of the file exactly as the scaffold wrote it.
+     *
+     * Compared against the file on disk before a stub is deleted. A mismatch means the file is no
+     * longer the placeholder that was written — free flight, the editor or a story implementation
+     * has been in it — so it is kept, and only the `stub` flag is dropped.
+     */
+    hash?: string;
+    /** This widget is on its area home's shortlist and renders there in `compact` mode too. */
+    home?: boolean;
+    /** Story code that OWNS the allocation — the one its file is named after. */
+    story: string;
+    /**
+     * Every story this one artifact stands in for, the owner included.
+     *
+     * A preview widget is drawn per user story only when each story genuinely needs its own; two
+     * steps of one flow that act on the same record through the same shape share ONE widget, and
+     * then the widget belongs to a SET. `story` stays the code the file is named after, because
+     * `widgetDefinition(code)` derives the filename from exactly one; this is what lets
+     * `byStory` answer to every member, and what stops a departing member from retiring an
+     * artifact the others still name.
+     *
+     * Absent on an artifact nobody shares — the ordinary case, and the shape every slot drawn
+     * before sharing existed carries.
+     */
+    stories?: string[];
+}
+/** Frontmatter for .agents/memory/registry.md */
+export interface RegistryMeta extends Record<string, unknown> {
+    version: number;
+    entries: RegistryAllocation[];
+}
+/**
+ * One place the repository no longer matches the layout the pipeline derives paths from.
+ *
+ * `expected` is what `naming.ts` would build; `actual` is what is on disk. Both are recorded
+ * because a later run has to do two different things with them — address the file where it is,
+ * and stop proposing to move it back.
+ */
+export interface LayoutDeviation {
+    /** What the pipeline would have derived — a repo-relative path or a directory. */
+    expected: string;
+    /** Where the thing actually is. Empty when it was removed outright. */
+    actual: string;
+    /** Why it moved, in one sentence, as the run that observed it understood it. */
+    reason: string;
+}
+/**
+ * Frontmatter for `.agents/memory/layout.md`.
+ *
+ * A generated target IS-A `@owlmeans/create-app` project, and every path the pipeline writes is
+ * derived from that. The volume is the user's, though: they rename, they move, they merge a pull
+ * request. Recording the divergence is what keeps the next run from fighting it — an agent that
+ * re-derives a path it was already told is wrong recreates the file in the old place, and the
+ * project then has two.
+ *
+ * `layout` is which of the two generated shapes the tree started as, so that a slot published
+ * before the `create-app` adoption is still addressed in its own vocabulary.
+ */
+export interface LayoutMeta extends Record<string, unknown> {
+    version: number;
+    /** `v1` (packages/{common,backend,frontend}) or `v2` (sources/*). */
+    layout: string;
+    updatedAt: string;
+    deviations: LayoutDeviation[];
+}
+//# sourceMappingURL=types.d.ts.map

package/build/metadata/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/metadata/types.ts"],"names":[],"mappings":"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"}

package/build/metadata/types.js

@@ -0,0 +1,39 @@
+export var MetadataKind;
+(function (MetadataKind) {
+    MetadataKind["Project"] = "project";
+    MetadataKind["Story"] = "story";
+    MetadataKind["Source"] = "source";
+    MetadataKind["History"] = "history";
+})(MetadataKind || (MetadataKind = {}));
+export var MetadataListKind;
+(function (MetadataListKind) {
+    MetadataListKind["Stories"] = "stories";
+    MetadataListKind["Meta"] = "meta";
+    // All metadata: the docs/ and .agents/ trees + co-located *.spec/.ux/.ui.md beside sources
+    MetadataListKind["All"] = "all";
+})(MetadataListKind || (MetadataListKind = {}));
+// ─── Name registry (.agents/memory/registry.md) ───────────────────────────────────────
+/**
+ * What a registry entry names.
+ *
+ * One entry per artifact the pipeline can generate, so that "where does this live" and "what is
+ * it called" have exactly one answer for the whole life of the project.
+ */
+export var RegistryKind;
+(function (RegistryKind) {
+    /** The single directory segment an entity owns across models/, resources/ and backend models/ */
+    RegistryKind["EntityDir"] = "entity-dir";
+    RegistryKind["ModelType"] = "model-type";
+    RegistryKind["Resource"] = "resource";
+    RegistryKind["BackendModel"] = "backend-model";
+    RegistryKind["ApiHandlers"] = "api-handlers";
+    RegistryKind["Service"] = "service";
+    RegistryKind["Layout"] = "layout";
+    RegistryKind["Screen"] = "screen";
+    RegistryKind["Component"] = "component";
+    RegistryKind["ViewModel"] = "view-model";
+    RegistryKind["State"] = "state";
+    /** Alias-only entry for one endpoint — carries no source path of its own */
+    RegistryKind["ApiEntrypoint"] = "api-entrypoint";
+})(RegistryKind || (RegistryKind = {}));
+//# sourceMappingURL=types.js.map

package/build/metadata/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/metadata/types.ts"],"names":[],"mappings":"AAcA,MAAM,CAAN,IAAY,YAKX;AALD,WAAY,YAAY;IACtB,mCAAmB,CAAA;IACnB,+BAAe,CAAA;IACf,iCAAiB,CAAA;IACjB,mCAAmB,CAAA;AACrB,CAAC,EALW,YAAY,KAAZ,YAAY,QAKvB;AAED,MAAM,CAAN,IAAY,gBAKX;AALD,WAAY,gBAAgB;IAC1B,uCAAmB,CAAA;IACnB,iCAAa,CAAA;IACb,2FAA2F;IAC3F,+BAAW,CAAA;AACb,CAAC,EALW,gBAAgB,KAAhB,gBAAgB,QAK3B;AAmJD,yFAAyF;AAEzF;;;;;GAKG;AACH,MAAM,CAAN,IAAY,YAeX;AAfD,WAAY,YAAY;IACtB,iGAAiG;IACjG,wCAAwB,CAAA;IACxB,wCAAwB,CAAA;IACxB,qCAAqB,CAAA;IACrB,8CAA8B,CAAA;IAC9B,4CAA4B,CAAA;IAC5B,mCAAmB,CAAA;IACnB,iCAAiB,CAAA;IACjB,iCAAiB,CAAA;IACjB,uCAAuB,CAAA;IACvB,wCAAwB,CAAA;IACxB,+BAAe,CAAA;IACf,4EAA4E;IAC5E,gDAAgC,CAAA;AAClC,CAAC,EAfW,YAAY,KAAZ,YAAY,QAevB"}

package/build/moderation/consts.d.ts

@@ -0,0 +1,58 @@
+/**
+ * What the moderation gate refuses, and nothing more.
+ *
+ * The set is deliberately about the SHAPE of what is being built, never its sector: a product
+ * that handles money, credentials or medical data is ordinary, and a platform that refuses
+ * those refuses most of its own market. What is not ordinary is a product whose purpose is to
+ * collect someone else's credentials, to be mistaken for someone who did not ask to be
+ * represented, or to push messages at people who never asked for them.
+ *
+ * Every generated app has a sign-in screen of its own — that is what an application is — so a
+ * login is never evidence of anything here.
+ *
+ * The set is CLOSED. A new refusal shape belongs inside one of these four, phrased into the
+ * policy prompt: each value is a wire contract with user-facing wording in seven languages
+ * behind it, and a fifth one silently renders as the generic refusal until every one of those
+ * catches up.
+ */
+export declare enum ModerationCategory {
+    /** Captures credentials, OTPs, card numbers or recovery phrases for a service the requester does not run. */
+    CredentialHarvesting = "credential-harvesting",
+    /** Presents itself as a named third party — an organization OR a real person — rather than as its own product. */
+    BrandImpersonation = "brand-impersonation",
+    /** Collects payment details on behalf of a merchant that is not the requester. */
+    PaymentCapture = "payment-capture",
+    /** Tooling whose purpose is abuse: credential stuffers, phishing-kit builders, bulk-spam senders. */
+    AbuseTooling = "abuse-tooling"
+}
+/**
+ * What is being classified. Carried into the trace so a refusal can be attributed.
+ *
+ * Each value has a framing sentence behind it that tells the classifier whose words it is
+ * reading — the same text means different things as a customer's request, as our own generated
+ * specification, and as a file already sitting inside an approved project.
+ */
+export declare enum ModerationSubject {
+    Prompt = "prompt",
+    Specification = "specification",
+    Story = "story",
+    /**
+     * A file a human wrote through the project's own editor.
+     *
+     * Deliberately separate from the three above: this is code inside an already-approved
+     * product, so the framing has to stop the classifier from refusing ordinary application
+     * source that happens to contain the word "password" or a payment form.
+     */
+    Source = "source",
+    /**
+     * What a project is CALLED — and, through its slug, what it is reachable at.
+     *
+     * The only subject that judges an identifier rather than a product, and the only one whose
+     * answer may disagree with {@link ModerationSubject.Specification} about the same brand. A
+     * consumer turns a project's name into a hostname on a domain all of its customers share, so
+     * "a dashboard for our Shopify store" is an ordinary thing to build while `shopify-dashboard`
+     * is not a name it may be reachable at. Descriptions may name a brand; identifiers may not.
+     */
+    Name = "name"
+}
+//# sourceMappingURL=consts.d.ts.map

package/build/moderation/consts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../../src/moderation/consts.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;GAgBG;AACH,oBAAY,kBAAkB;IAC5B,6GAA6G;IAC7G,oBAAoB,0BAA0B;IAC9C,kHAAkH;IAClH,kBAAkB,wBAAwB;IAC1C,kFAAkF;IAClF,cAAc,oBAAoB;IAClC,qGAAqG;IACrG,YAAY,kBAAkB;CAC/B;AAED;;;;;;GAMG;AACH,oBAAY,iBAAiB;IAC3B,MAAM,WAAW;IACjB,aAAa,kBAAkB;IAC/B,KAAK,UAAU;IACf;;;;;;OAMG;IACH,MAAM,WAAW;IACjB;;;;;;;;OAQG;IACH,IAAI,SAAS;CACd"}

package/build/moderation/consts.js

@@ -0,0 +1,60 @@
+/**
+ * What the moderation gate refuses, and nothing more.
+ *
+ * The set is deliberately about the SHAPE of what is being built, never its sector: a product
+ * that handles money, credentials or medical data is ordinary, and a platform that refuses
+ * those refuses most of its own market. What is not ordinary is a product whose purpose is to
+ * collect someone else's credentials, to be mistaken for someone who did not ask to be
+ * represented, or to push messages at people who never asked for them.
+ *
+ * Every generated app has a sign-in screen of its own — that is what an application is — so a
+ * login is never evidence of anything here.
+ *
+ * The set is CLOSED. A new refusal shape belongs inside one of these four, phrased into the
+ * policy prompt: each value is a wire contract with user-facing wording in seven languages
+ * behind it, and a fifth one silently renders as the generic refusal until every one of those
+ * catches up.
+ */
+export var ModerationCategory;
+(function (ModerationCategory) {
+    /** Captures credentials, OTPs, card numbers or recovery phrases for a service the requester does not run. */
+    ModerationCategory["CredentialHarvesting"] = "credential-harvesting";
+    /** Presents itself as a named third party — an organization OR a real person — rather than as its own product. */
+    ModerationCategory["BrandImpersonation"] = "brand-impersonation";
+    /** Collects payment details on behalf of a merchant that is not the requester. */
+    ModerationCategory["PaymentCapture"] = "payment-capture";
+    /** Tooling whose purpose is abuse: credential stuffers, phishing-kit builders, bulk-spam senders. */
+    ModerationCategory["AbuseTooling"] = "abuse-tooling";
+})(ModerationCategory || (ModerationCategory = {}));
+/**
+ * What is being classified. Carried into the trace so a refusal can be attributed.
+ *
+ * Each value has a framing sentence behind it that tells the classifier whose words it is
+ * reading — the same text means different things as a customer's request, as our own generated
+ * specification, and as a file already sitting inside an approved project.
+ */
+export var ModerationSubject;
+(function (ModerationSubject) {
+    ModerationSubject["Prompt"] = "prompt";
+    ModerationSubject["Specification"] = "specification";
+    ModerationSubject["Story"] = "story";
+    /**
+     * A file a human wrote through the project's own editor.
+     *
+     * Deliberately separate from the three above: this is code inside an already-approved
+     * product, so the framing has to stop the classifier from refusing ordinary application
+     * source that happens to contain the word "password" or a payment form.
+     */
+    ModerationSubject["Source"] = "source";
+    /**
+     * What a project is CALLED — and, through its slug, what it is reachable at.
+     *
+     * The only subject that judges an identifier rather than a product, and the only one whose
+     * answer may disagree with {@link ModerationSubject.Specification} about the same brand. A
+     * consumer turns a project's name into a hostname on a domain all of its customers share, so
+     * "a dashboard for our Shopify store" is an ordinary thing to build while `shopify-dashboard`
+     * is not a name it may be reachable at. Descriptions may name a brand; identifiers may not.
+     */
+    ModerationSubject["Name"] = "name";
+})(ModerationSubject || (ModerationSubject = {}));
+//# sourceMappingURL=consts.js.map

package/build/moderation/consts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../../src/moderation/consts.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAN,IAAY,kBASX;AATD,WAAY,kBAAkB;IAC5B,6GAA6G;IAC7G,oEAA8C,CAAA;IAC9C,kHAAkH;IAClH,gEAA0C,CAAA;IAC1C,kFAAkF;IAClF,wDAAkC,CAAA;IAClC,qGAAqG;IACrG,oDAA8B,CAAA;AAChC,CAAC,EATW,kBAAkB,KAAlB,kBAAkB,QAS7B;AAED;;;;;;GAMG;AACH,MAAM,CAAN,IAAY,iBAsBX;AAtBD,WAAY,iBAAiB;IAC3B,sCAAiB,CAAA;IACjB,oDAA+B,CAAA;IAC/B,oCAAe,CAAA;IACf;;;;;;OAMG;IACH,sCAAiB,CAAA;IACjB;;;;;;;;OAQG;IACH,kCAAa,CAAA;AACf,CAAC,EAtBW,iBAAiB,KAAjB,iBAAiB,QAsB5B"}

package/build/moderation/index.d.ts

@@ -0,0 +1,5 @@
+export * from './consts.js';
+export * from './schemas.js';
+export * from './utils.js';
+export type * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/build/moderation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/moderation/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,mBAAmB,YAAY,CAAA"}

package/build/moderation/index.js

@@ -0,0 +1,4 @@
+export * from './consts.js';
+export * from './schemas.js';
+export * from './utils.js';
+//# sourceMappingURL=index.js.map

package/build/moderation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/moderation/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA"}

package/build/moderation/schemas.d.ts

@@ -0,0 +1,19 @@
+import type { JSONSchemaType } from 'ajv';
+import type { ModerationVerdict } from './types.js';
+/**
+ * What the classifier must answer with.
+ *
+ * Kept minimal on purpose: a schema the model must satisfy is also a schema it will try to
+ * fill, and every extra field is another thing it can hallucinate a reason into. The decision
+ * is one boolean; the category exists so the browser can phrase the refusal; the evidence
+ * exists so a human reviewing the trace can see what the model actually reacted to.
+ *
+ * `category` is a free string here even though only `ModerationCategory` values mean anything,
+ * and that is deliberate. Constrained to the enum it made **every** call fail: with nothing to
+ * categorise, a model that allows still fills the field — `"none"`, `""`, `"n/a"` — the
+ * response fails validation, the retry budget runs out, and the gate fails open on every
+ * request while looking like it is working. The value is narrowed in code instead
+ * (`normalizeCategory`), where an unrecognized one is simply absent.
+ */
+export declare const ModerationVerdictSchema: JSONSchemaType<ModerationVerdict>;
+//# sourceMappingURL=schemas.d.ts.map

package/build/moderation/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/moderation/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,KAAK,CAAA;AACzC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEnD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,uBAAuB,EAAE,cAAc,CAAC,iBAAiB,CASrB,CAAA"}

package/build/moderation/schemas.js

@@ -0,0 +1,26 @@
+/**
+ * What the classifier must answer with.
+ *
+ * Kept minimal on purpose: a schema the model must satisfy is also a schema it will try to
+ * fill, and every extra field is another thing it can hallucinate a reason into. The decision
+ * is one boolean; the category exists so the browser can phrase the refusal; the evidence
+ * exists so a human reviewing the trace can see what the model actually reacted to.
+ *
+ * `category` is a free string here even though only `ModerationCategory` values mean anything,
+ * and that is deliberate. Constrained to the enum it made **every** call fail: with nothing to
+ * categorise, a model that allows still fills the field — `"none"`, `""`, `"n/a"` — the
+ * response fails validation, the retry budget runs out, and the gate fails open on every
+ * request while looking like it is working. The value is narrowed in code instead
+ * (`normalizeCategory`), where an unrecognized one is simply absent.
+ */
+export const ModerationVerdictSchema = {
+    type: 'object',
+    properties: {
+        allowed: { type: 'boolean' },
+        category: { type: 'string', maxLength: 64, nullable: true },
+        evidence: { type: 'string', maxLength: 500, nullable: true },
+    },
+    required: ['allowed'],
+    additionalProperties: false,
+};
+//# sourceMappingURL=schemas.js.map

package/build/moderation/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../src/moderation/schemas.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAsC;IACxE,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,OAAO,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;QAC5B,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE;QAC3D,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE;KAC7D;IACD,QAAQ,EAAE,CAAC,SAAS,CAAC;IACrB,oBAAoB,EAAE,KAAK;CACoB,CAAA"}

package/build/moderation/types.d.ts

@@ -0,0 +1,64 @@
+import type { ModerationCategory, ModerationSubject } from './consts.js';
+/**
+ * What the moderation classifier returns.
+ *
+ * `evidence` is diagnostic only — it reaches the trace and the logs, never the user. What the
+ * user is told derives from `category` in the browser, so a refusal reads the same in all
+ * seven languages and the model never gets to write UI copy.
+ */
+export interface ModerationVerdict {
+    allowed: boolean;
+    /**
+     * Free string on the wire, narrowed to {@link ModerationCategory} by `normalizeCategory`.
+     * A model that is allowing has nothing to categorise and will still put something here.
+     */
+    category?: string;
+    evidence?: string;
+}
+/**
+ * The three outcomes, separated from the IO so the policy can be read and tested on its own.
+ *
+ * `shadow` means the verdict was negative and is being recorded but not acted on.
+ */
+export type ModerationAction = 'allow' | 'refuse' | 'shadow';
+/**
+ * The two operational levers on the gate.
+ *
+ * Both exist because a blocking classifier will eventually be wrong about a real customer, and
+ * at that moment the fix has to be faster than a deploy. `enforce: false` keeps the verdicts
+ * flowing into the traces while refusing nothing, which is also how a change to the policy
+ * prompt should be evaluated before it is trusted.
+ */
+export interface ModerationPolicy {
+    /** Defaults to ON. Set false to compute and trace verdicts without acting on them. */
+    enforce?: boolean;
+    /** Entity ids released from the gate entirely. */
+    bypassEntities?: string[];
+}
+/** What a caller needs in order to refuse: never the model's own words. */
+export interface ModerationOutcome {
+    action: ModerationAction;
+    /**
+     * Always present when `action` is not `allow`.
+     *
+     * A refusal has to tell the user something specific, so an unrecognized category from the
+     * model is replaced rather than dropped — see `normalizeCategory`.
+     */
+    category?: ModerationCategory;
+    /** Diagnostic only. Logged and traced, never rendered. */
+    evidence?: string;
+}
+/** One classification request. */
+export interface ModerationInput {
+    subject: ModerationSubject;
+    /** One text, or several judged together — several is one call, not several. */
+    text: string | string[];
+    /** Whose request this is — the one thing a bypass can be keyed on. */
+    entityId?: string;
+    /**
+     * Extra framing appended to the subject's own, for a subject whose meaning depends on where
+     * the text came from — a file's path, for instance.
+     */
+    context?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/moderation/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/moderation/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAExE;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAA;IAChB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAE5D;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,sFAAsF;IACtF,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,kDAAkD;IAClD,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;CAC1B;AAED,2EAA2E;AAC3E,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,gBAAgB,CAAA;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,kBAAkB,CAAA;IAC7B,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,kCAAkC;AAClC,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,iBAAiB,CAAA;IAC1B,+EAA+E;IAC/E,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IACvB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB"}

package/build/moderation/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/moderation/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/moderation/types.ts"],"names":[],"mappings":""}

package/build/moderation/utils.d.ts

@@ -0,0 +1,21 @@
+import { ModerationCategory } from './consts.js';
+import type { ModerationAction, ModerationPolicy, ModerationVerdict } from './types.js';
+/**
+ * Narrow whatever the model put in `category` to a real one, or to nothing.
+ *
+ * The wire field is a free string on purpose — see {@link ModerationVerdictSchema}. A model
+ * that is allowing has nothing to categorise and still fills the field, so anything
+ * unrecognized is treated as absent rather than as a failure.
+ */
+export declare const normalizeCategory: (category?: string) => ModerationCategory | undefined;
+/**
+ * What to do about a verdict.
+ *
+ * Pure, because this is the part with the operational levers on it and the part most likely
+ * to be wrong in a hurry: `enforce` turns the whole gate into an observer without a deploy,
+ * and `bypassEntities` releases one entity when a real customer is wrongly refused.
+ */
+export declare const decideModeration: (verdict: ModerationVerdict, policy?: ModerationPolicy & {
+    entityId?: string;
+}) => ModerationAction;
+//# sourceMappingURL=utils.d.ts.map

package/build/moderation/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/moderation/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEvF;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,cAAe,MAAM,KAAG,kBAAkB,GAAG,SAM1E,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,YAClB,iBAAiB,WAAU,gBAAgB,GAAG;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,KAC3E,gBAOF,CAAA"}