@vibesdotdev/moderation 0.0.0-stage → 1.0.0-rc.5

package/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 VIBES DEV LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,84 @@
-# Temporary Holding Version
+# @vibesdotdev/moderation
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Judge user content with an AI evaluation battery and turn the scores into `allow`, `review` or `hide`.
+
+## Install
+
+`bun add @vibesdotdev/moderation` using the Vibes package registry.
+
+## Usage
+
+1. **Register a battery** in the feature that owns the content: one `noul` head per label, named exactly as the label, and a non-empty `requiredState`.
+
+   ```ts
+   import { createAIEvaluationSchemaDescriptor } from '@vibesdotdev/ai/schemas';
+
+   export default createAIEvaluationSchemaDescriptor({
+       id: 'posts.moderation',
+       name: 'Post moderation',
+       description: 'Scores a post against the moderation labels',
+       requiredState: ['post'],
+       questions: {
+           spam: { type: 'noul', instructions: 'The post is unsolicited bulk, repetitive or off-topic promotion.' },
+           scam: { type: 'noul', instructions: 'The post tries to obtain money, credentials or personal data by fraud.' }
+       }
+   });
+   ```
+
+2. **Register a subject** for the content, naming the battery and the thresholds.
+
+   ```ts
+   import { createModerationSubjectDescriptor } from '@vibesdotdev/moderation/schemas';
+
+   export default createModerationSubjectDescriptor({
+       id: 'posts.post',
+       name: 'Post',
+       description: 'A published post',
+       batteryId: 'posts.moderation',
+       labels: ['spam', 'scam'],
+       thresholds: { default: { reviewAt: 0.5, hideAt: 0.85 } }
+   });
+   ```
+
+3. **Moderate** with the runtime that composes `moderationPlugin` (from `@vibesdotdev/moderation/plugin`), the feature's plugin and the canonical public `AIClient`. AI owns battery and answer contracts; moderation owns label coverage and thresholds. Pass a plain JSON state object; moderation snapshots it before asynchronous work.
+
+   ```ts
+   import { moderateSubject } from '@vibesdotdev/moderation';
+
+   const decision = await moderateSubject(runtime, {
+       subject: { type: 'posts.post', id: post.id },
+       state: { post: post.body }
+   });
+   ```
+
+4. **Override thresholds** in a host by registering the host's own subject id against the same battery, then passing that id as `subject.type`. A feature's subject cannot be re-registered.
+
+The `.` entrypoint exports the isomorphic contract, policy and orchestration.
+`./plugin` exports moderationPlugin; `./schemas` exports moderation schemas,
+inferred types and descriptor factories without runtime orchestration.
+
+`decideModeration` validates its policy before applying thresholds. Invalid
+ranges, inverted thresholds and undeclared overrides throw `ZodError`.
+Malformed orchestration envelopes, references and options (including null) also throw `ZodError`. Omitted or undefined options use the defaults.
+Domain refusals throw `ModerationError` with a standard CapabilityError code,
+moderationCode and kebab-case reason. Accessors and cycles are refused before
+inference; caller-object exceptions and unrelated AI failures propagate unchanged.
+Adapted answers can review but cannot hide.
+
+Run `bun run check`, `bun run test` and `bun run build` in this package.
+Tests exercise public source entrypoints on owned runtimes and check schemas,
+declared export mappings, publication exclusions and universal source closures.
+The check project includes tests; the build project emits production JavaScript
+and declarations. Tests require no prebuilt dist and run in process.
+
+Distributed-artifact verification belongs to the canonical release preflight in
+`@vibesdotdev/infra-deploy` (`stagePackageForPublish` and
+`verifyPackedPackage`). Actual packed contents, published dependency range
+conversion, Node compatibility and emitted-declaration consumption require
+release evidence; source/manifest checks and compilation do not prove them.
+
+See [SPEC.md](./SPEC.md) for the contract and the error codes.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/dist/decide.d.ts

@@ -0,0 +1,16 @@
+import { type ModerationDecision, type ModerationLabel } from './schemas/decision.ts';
+import { type ModerationSubjectDescriptor } from './schemas/subject.ts';
+/**
+ * The threshold policy. Pure: no runtime, no clock, no I/O.
+ *
+ * Each label uses its subject's per-label thresholds, else the default. A
+ * native score at or above `hideAt` is a hide trigger; otherwise a score at
+ * or above `reviewAt` is a review trigger. Adapted (JSON-mode) scores are
+ * uncalibrated, so they can reach review but never hide.
+ *
+ * The labels must cover exactly the subject's labels, for one subject, from
+ * one battery and one answer source; anything else throws
+ * MODERATION_EVALUATION_INVALID.
+ */
+export declare function decideModeration(subject: ModerationSubjectDescriptor, labels: readonly ModerationLabel[], decidedAt: Date): ModerationDecision;
+//# sourceMappingURL=decide.d.ts.map

package/dist/decide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decide.d.ts","sourceRoot":"","sources":["../src/decide.ts"],"names":[],"mappings":"AACA,OAAO,EAEN,KAAK,kBAAkB,EACvB,KAAK,eAAe,EAEpB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAqC,KAAK,2BAA2B,EAAE,MAAM,sBAAsB,CAAC;AAE3G;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC/B,OAAO,EAAE,2BAA2B,EACpC,MAAM,EAAE,SAAS,eAAe,EAAE,EAClC,SAAS,EAAE,IAAI,GACb,kBAAkB,CA+EpB"}

package/dist/decide.js

@@ -0,0 +1,81 @@
+import { ModerationError } from "./errors.js";
+import { ModerationDecisionSchema } from "./schemas/decision.js";
+import { ModerationSubjectDescriptorSchema } from "./schemas/subject.js";
+/**
+ * The threshold policy. Pure: no runtime, no clock, no I/O.
+ *
+ * Each label uses its subject's per-label thresholds, else the default. A
+ * native score at or above `hideAt` is a hide trigger; otherwise a score at
+ * or above `reviewAt` is a review trigger. Adapted (JSON-mode) scores are
+ * uncalibrated, so they can reach review but never hide.
+ *
+ * The labels must cover exactly the subject's labels, for one subject, from
+ * one battery and one answer source; anything else throws
+ * MODERATION_EVALUATION_INVALID.
+ */
+export function decideModeration(subject, labels, decidedAt) {
+    subject = ModerationSubjectDescriptorSchema.parse(subject);
+    const invalid = (reason) => new ModerationError('MODERATION_EVALUATION_INVALID', `labels do not cover subject '${subject.id}' labels exactly: ${reason}`);
+    const [first] = labels;
+    if (!first)
+        throw invalid('no labels');
+    const values = labels.map((label) => label.value);
+    const covers = values.length === subject.labels.length &&
+        new Set(values).size === values.length &&
+        subject.labels.every((value) => values.includes(value));
+    if (!covers) {
+        throw invalid(`got [${values.join(', ')}], expected [${subject.labels.join(', ')}]`);
+    }
+    const ref = first.subject;
+    if (ref.type !== subject.id) {
+        throw invalid(`labels name '${ref.type}', not policy subject '${subject.id}'`);
+    }
+    if (!labels.every((label) => label.subject.type === ref.type &&
+        label.subject.id === ref.id &&
+        label.subject.containerId === ref.containerId)) {
+        throw invalid('labels disagree on subject');
+    }
+    const source = first.source;
+    if (!labels.every((label) => label.source.batteryId === source.batteryId &&
+        label.source.answerSource === source.answerSource)) {
+        throw invalid('labels disagree on source');
+    }
+    if (source.batteryId !== subject.batteryId) {
+        throw invalid(`labels come from battery '${source.batteryId}', not '${subject.batteryId}'`);
+    }
+    const triggers = [];
+    for (const label of labels) {
+        const thresholds = subject.thresholds.labels?.[label.value] ?? subject.thresholds.default;
+        if (source.answerSource === 'native' && label.score >= thresholds.hideAt) {
+            triggers.push({
+                label: label.value,
+                score: label.score,
+                threshold: thresholds.hideAt,
+                level: 'hide'
+            });
+        }
+        else if (label.score >= thresholds.reviewAt) {
+            triggers.push({
+                label: label.value,
+                score: label.score,
+                threshold: thresholds.reviewAt,
+                level: 'review'
+            });
+        }
+    }
+    triggers.sort((a, b) => b.score - a.score);
+    const action = triggers.some((trigger) => trigger.level === 'hide')
+        ? 'hide'
+        : triggers.length > 0
+            ? 'review'
+            : 'allow';
+    return ModerationDecisionSchema.parse({
+        subject: ref,
+        action,
+        answerSource: source.answerSource,
+        labels: [...labels],
+        triggers,
+        decidedAt: decidedAt.toISOString()
+    });
+}
+//# sourceMappingURL=decide.js.map

package/dist/decide.js.map

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

package/dist/docs/moderation.decisions.docs.descriptor.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Descriptor for moderation.decisions — moderateSubject, the threshold
+ * policy, the label and decision records, and the error codes. Pure data:
+ * no imports.
+ */
+declare const descriptor: {
+    kind: "docs/topic";
+    id: string;
+    title: string;
+    summary: string;
+    parent: string;
+    body: {
+        type: "markdown";
+        sourceType: "raw";
+        source: string;
+    };
+    order: number;
+    tags: string[];
+    surfaces: string[];
+    hardware: string[];
+    enabled: boolean;
+};
+export default descriptor;
+//# sourceMappingURL=moderation.decisions.docs.descriptor.d.ts.map

package/dist/docs/moderation.decisions.docs.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"moderation.decisions.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/moderation.decisions.docs.descriptor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAyEH,QAAA,MAAM,UAAU;;;;;;;;;;;;;;;;CAiBf,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/moderation.decisions.docs.descriptor.js

@@ -0,0 +1,94 @@
+/**
+ * Descriptor for moderation.decisions — moderateSubject, the threshold
+ * policy, the label and decision records, and the error codes. Pure data:
+ * no imports.
+ */
+const moderationDecisionsMarkdown = `---
+title: Moderation Decisions
+summary: moderateSubject, the threshold policy, the label and decision records, and every moderation error code
+tags: [moderation, decisions, labels, thresholds, errors]
+parent: moderation
+order: 2
+---
+
+# Moderation Decisions
+
+## moderateSubject
+
+\`moderateSubject(runtime, { subject, state }, { now? })\` judges one subject on the runtime you pass and returns a validated decision. It runs in this order, and every precondition fails before any inference is spent:
+
+1. Validate the envelope derived from \`ModerateSubjectInputSchema\`, options with \`ModerateSubjectOptionsSchema\`, and \`subject\` with \`ModerationSubjectRefSchema\` and snapshot plain JSON \`state\` before the first await. A malformed ref throws the parse error; non-JSON state throws \`MODERATION_STATE_INVALID\`. An accessor property is refused without being read and a cycle is refused by its path; any other non-JSON value fails the state schema, whose error is the \`cause\`. A failure the caller's own object raises while it is read (a proxy trap, or nesting deeper than the call stack) propagates unchanged.
+2. Resolve the enabled \`moderation/subject\` whose id is \`subject.type\`.
+3. Resolve the subject's \`ai/evaluation-schema\` battery once.
+4. Check the battery contract: heads equal the labels, every head is \`noul\`, \`requiredState\` is non-empty.
+5. Check the owned state snapshot: every \`requiredState\` key is present and not null, blank or an empty list. Caller replacement or nested mutation cannot alter the observation passed to inference.
+6. Resolve runtime/client \`ai\`. If the runtime has no \`runtime/client\` kind, moderation refuses rather than registering one. If \`ai\` is not registered, it refuses with that absence as the \`cause\`; any other failure while loading the client propagates unchanged with its own code.
+7. Call \`evaluate({ schemaId, questions, state })\` with the already-resolved questions, so the battery is not resolved a second time. \`schemaId\` keeps scorecard attribution.
+8. Validate the answers: one \`noul\` in \`[0, 1]\` per label, no missing and no undeclared heads.
+9. Apply \`decideModeration\` and return the decision.
+
+Evaluator errors, including "no evaluation model", propagate unchanged. Nothing is stored or enqueued.
+
+## The threshold policy
+
+\`decideModeration(subject, labels, decidedAt)\` first validates the policy with \`ModerationSubjectDescriptorSchema\`. Out-of-range or inverted thresholds and invalid label overrides throw \`ZodError\` before a decision. It is pure. For each label it uses the per-label thresholds, else the default:
+
+- a **native** score at or above \`hideAt\` is a \`hide\` trigger at that threshold;
+- otherwise a score at or above \`reviewAt\` is a \`review\` trigger.
+
+The action is \`hide\` if any trigger hides, \`review\` if any trigger exists, else \`allow\`. Triggers are sorted by score, highest first.
+
+**Adapted answers never hide.** A JSON-mode model running the battery returns \`source: 'adapted'\`; its numbers are not calibrated probabilities. Adapted scores can reach \`review\` but never \`hide\`, and the decision records \`answerSource\` so a reader can tell. An absent source reads as \`native\`.
+
+The labels must cover exactly the subject's labels, with their subject type equal to the policy descriptor's id, from the subject's battery and one answer source. Sharing a battery does not authorize another subject's thresholds. Anything else throws \`MODERATION_EVALUATION_INVALID\` ("labels do not cover subject … labels exactly").
+
+Decision records reject duplicate trigger labels, scores that differ from the carried label, and scores below the recorded threshold. Validation does not reconstruct an absent policy or infer missing triggers.
+
+## Records
+
+| Schema | Shape |
+|---|---|
+| \`ModerationAnswerSourceSchema\` | \`'native'\` or \`'adapted'\` |
+| \`ModerationLabelSchema\` | \`{ subject, value, score, source: { batteryId, answerSource } }\` |
+| \`ModerationActionSchema\` | \`'allow'\`, \`'review'\` or \`'hide'\` |
+| \`ModerationTriggerSchema\` | \`{ label, score, threshold, level: 'review' \\| 'hide' }\` |
+| \`ModerationDecisionSchema\` | \`{ subject, action, answerSource, labels, triggers, decidedAt }\` |
+
+\`ModerationDecisionSchema\` refuses inconsistent decisions: \`allow\` exactly when there are no triggers, \`hide\` exactly when a trigger hides, no hide trigger from adapted answers, unique label values, every label about the decision's subject and from its answer source, and every trigger naming a carried label.
+
+Input contracts also expose \`ModerationStateSchema\` and \`ModerationStateInputSchema\`. Orchestration leaves caller state opaque until safe inspection and snapshot validation; the public input schema describes JSON state. Public types are inferred; \`ModerationErrorCodeSchema\` validates refusal codes.
+
+Only omitted or undefined options use defaults; null is malformed. Malformed envelopes, references and options throw \`ZodError\`. Caller-object exceptions propagate unchanged.
+
+## Errors
+
+\`ModerationError\` is a \`CapabilityError\`. Its \`moderationCode\` comes from \`MODERATION_ERROR_CODES\`, its \`reason\` is that code in kebab case, and \`details.moderationCode\` repeats it. Its \`code\` stays the standard one, \`NOT_FOUND\` for the two unknown codes, \`UNAVAILABLE\` for \`MODERATION_EVALUATOR_UNAVAILABLE\` and \`INVALID_INPUT\` for the rest, so \`exitCode\`, \`httpStatus\` and \`toEnvelope()\` map every failure on the CLI and the web. Its message starts with \`<moderationCode>: \`, and a wrapped failure is its \`cause\`.
+
+| Code | Raised when |
+|---|---|
+| \`MODERATION_SUBJECT_UNKNOWN\` | No enabled subject has the requested id, the kind is not mounted, or the registered subject fails the subject schema |
+| \`MODERATION_BATTERY_UNKNOWN\` | The subject's battery is not registered or is disabled |
+| \`MODERATION_BATTERY_MISMATCH\` | The battery is not a readable evaluation battery, or breaks the contract above |
+| \`MODERATION_STATE_INVALID\` | \`state\` is not a plain JSON object (an accessor or a cycle is named by path), or a required key is missing or empty; the message names the keys |
+| \`MODERATION_EVALUATOR_UNAVAILABLE\` | runtime/client is not composed, \`ai\` is not registered on it, or the client has no \`evaluate\` |
+| \`MODERATION_EVALUATION_INVALID\` | The answers do not match the battery, or the labels do not cover the subject |
+`;
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'moderation.decisions',
+    title: 'Moderation Decisions',
+    summary: 'moderateSubject, the threshold policy, the label and decision records, and every moderation error code',
+    parent: 'moderation',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: moderationDecisionsMarkdown
+    },
+    order: 2,
+    tags: ['moderation', 'decisions', 'labels', 'thresholds', 'errors'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=moderation.decisions.docs.descriptor.js.map

package/dist/docs/moderation.decisions.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"moderation.decisions.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/moderation.decisions.docs.descriptor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,2BAA2B,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqEnC,CAAC;AAEF,MAAM,UAAU,GAAG;IAClB,IAAI,EAAE,YAAqB;IAC3B,EAAE,EAAE,sBAAsB;IAC1B,KAAK,EAAE,sBAAsB;IAC7B,OAAO,EACN,wGAAwG;IACzG,MAAM,EAAE,YAAY;IACpB,IAAI,EAAE;QACL,IAAI,EAAE,UAAmB;QACzB,UAAU,EAAE,KAAc;QAC1B,MAAM,EAAE,2BAA2B;KACnC;IACD,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,CAAC;IACnE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/moderation.docs.descriptor.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Descriptor for moderation — the root topic of the moderation docs tree.
+ * Pure data: no imports.
+ */
+declare const descriptor: {
+    kind: "docs/topic";
+    id: string;
+    title: string;
+    summary: string;
+    body: {
+        type: "markdown";
+        sourceType: "raw";
+        source: string;
+    };
+    order: number;
+    tags: string[];
+    surfaces: string[];
+    hardware: string[];
+    enabled: boolean;
+};
+export default descriptor;
+//# sourceMappingURL=moderation.docs.descriptor.d.ts.map

package/dist/docs/moderation.docs.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"moderation.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/moderation.docs.descriptor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAiDH,QAAA,MAAM,UAAU;;;;;;;;;;;;;;;CAgBf,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/moderation.docs.descriptor.js

@@ -0,0 +1,68 @@
+/**
+ * Descriptor for moderation — the root topic of the moderation docs tree.
+ * Pure data: no imports.
+ */
+const moderationMarkdown = `---
+title: Moderation
+summary: Judge user content with an AI evaluation battery and turn the scores into allow, review or hide
+tags: [moderation, safety, labels, overview]
+order: 20
+---
+
+# Moderation
+
+\`@vibesdotdev/moderation\` is the one owner of content-moderation policy: which labels exist, how a feature declares a moderatable content type, and how label scores become an action. Features own their content, their battery and their subject. Model choice stays in \`ai\`: any structured-evaluation provider can answer a moderation battery.
+
+## When to use
+
+- A feature accepts user content (a chat message, a post, a comment) and needs a label-by-label judgment of it.
+- A host needs different thresholds from a feature's default without forking the feature.
+- Code needs a validated label or decision record to store, show or act on.
+
+## The pieces
+
+| Piece | What it is | Who provides it |
+|---|---|---|
+| \`moderation/subject\` | A moderatable content type: its battery, labels and thresholds | The feature that owns the content, or a host overriding it |
+| \`ai/evaluation-schema\` battery | One \`noul\` question per label, named exactly as the label | The same feature |
+| runtime/client \`ai\` | The evaluator that answers the battery | The host's AI composition |
+
+\`\`\`ts
+import { moderateSubject } from '@vibesdotdev/moderation';
+
+const decision = await moderateSubject(runtime, {
+	subject: { type: 'chat.message', id: message.id, containerId: room.id },
+	state: { message: message.content }
+});
+// decision.action is 'allow', 'review' or 'hide'
+\`\`\`
+
+\`moderateSubject\` resolves everything on the runtime you pass. It persists nothing and enqueues nothing: storing decisions, queues and the moderator console are separate.
+
+## Registering
+
+Compose \`moderationPlugin\` (the default export of \`@vibesdotdev/moderation/plugin\`, id \`moderation\`) once. It registers the \`moderation/subject\` kind and these docs. Features register their subjects and batteries from their own plugins; the descriptors queue until the kind registers, so order does not matter.
+
+:::card{title="In this section"}
+- [\`moderation.subjects\`](moderation.subjects) — the subject kind, the label vocabulary, the battery contract, thresholds and the host override
+- [\`moderation.decisions\`](moderation.decisions) — \`moderateSubject\`, the threshold policy, the label and decision records, and the error codes
+:::
+`;
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'moderation',
+    title: 'Moderation',
+    summary: 'Judge user content with an AI evaluation battery and turn the scores into allow, review or hide',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: moderationMarkdown
+    },
+    order: 20,
+    tags: ['moderation', 'safety', 'labels', 'overview'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=moderation.docs.descriptor.js.map

package/dist/docs/moderation.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"moderation.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/moderation.docs.descriptor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,kBAAkB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6C1B,CAAC;AAEF,MAAM,UAAU,GAAG;IAClB,IAAI,EAAE,YAAqB;IAC3B,EAAE,EAAE,YAAY;IAChB,KAAK,EAAE,YAAY;IACnB,OAAO,EACN,iGAAiG;IAClG,IAAI,EAAE;QACL,IAAI,EAAE,UAAmB;QACzB,UAAU,EAAE,KAAc;QAC1B,MAAM,EAAE,kBAAkB;KAC1B;IACD,KAAK,EAAE,EAAE;IACT,IAAI,EAAE,CAAC,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,CAAC;IACpD,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/moderation.subjects.docs.descriptor.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Descriptor for moderation.subjects — the `moderation/subject` kind, the
+ * label vocabulary and the battery contract. Pure data: no imports.
+ */
+declare const descriptor: {
+    kind: "docs/topic";
+    id: string;
+    title: string;
+    summary: string;
+    parent: string;
+    body: {
+        type: "markdown";
+        sourceType: "raw";
+        source: string;
+    };
+    order: number;
+    tags: string[];
+    surfaces: string[];
+    hardware: string[];
+    enabled: boolean;
+};
+export default descriptor;
+//# sourceMappingURL=moderation.subjects.docs.descriptor.d.ts.map

package/dist/docs/moderation.subjects.docs.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"moderation.subjects.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/moderation.subjects.docs.descriptor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA+EH,QAAA,MAAM,UAAU;;;;;;;;;;;;;;;;CAiBf,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/moderation.subjects.docs.descriptor.js

@@ -0,0 +1,99 @@
+/**
+ * Descriptor for moderation.subjects — the `moderation/subject` kind, the
+ * label vocabulary and the battery contract. Pure data: no imports.
+ */
+const moderationSubjectsMarkdown = `---
+title: Moderation Subjects
+summary: The moderation/subject kind — a feature's content type, its battery, its labels and its thresholds
+tags: [moderation, subjects, labels, thresholds, battery]
+parent: moderation
+order: 1
+---
+
+# Moderation Subjects
+
+A subject is one moderatable content type, registered as a \`moderation/subject\` descriptor (\`MODERATION_SUBJECT_KIND_ID\`) by the feature that owns the content. The kind object is \`moderationSubjectKind\`: descriptor-only, single-owner, with no default implementation and no loaders.
+
+## The descriptor
+
+\`ModerationSubjectDescriptorSchema\` extends the runtime descriptor with:
+
+| Field | Meaning |
+|---|---|
+| \`id\` | \`<feature>.<subject>\`, for example \`chat.message\` |
+| \`name\`, \`description\` | Non-empty |
+| \`batteryId\` | The \`ai/evaluation-schema\` battery that judges this content |
+| \`labels\` | The labels this subject scores; unique, at least one |
+| \`thresholds.default\` | \`{ reviewAt, hideAt }\` for every label |
+| \`thresholds.labels\` | Optional per-label overrides; each key must be one of \`labels\` |
+
+\`ModerationThresholdsSchema\` holds two scores in \`[0, 1]\` with \`reviewAt <= hideAt\`. Build a descriptor with \`createModerationSubjectDescriptor\`, which parses the input and stamps the kind:
+
+\`\`\`ts
+import { createModerationSubjectDescriptor } from '@vibesdotdev/moderation/schemas';
+
+export default createModerationSubjectDescriptor({
+	id: 'chat.message',
+	name: 'Chat message',
+	description: 'A message posted to a chat room',
+	batteryId: 'chat.moderation',
+	labels: ['harassment', 'hate', 'sexual', 'sexual_minors', 'violence', 'self_harm', 'spam', 'scam'],
+	thresholds: {
+		default: { reviewAt: 0.5, hideAt: 0.85 },
+		labels: { sexual_minors: { reviewAt: 0.2, hideAt: 0.5 } }
+	}
+});
+\`\`\`
+
+\`ModerationSubjectRefSchema\` names one piece of content: \`{ type, id, containerId? }\`, where \`type\` is a subject id.
+
+## Labels
+
+\`MODERATION_LABELS\` is a closed vocabulary of eight: \`harassment\`, \`hate\`, \`sexual\`, \`sexual_minors\`, \`violence\`, \`self_harm\`, \`spam\` and \`scam\`. \`ModerationLabelValueSchema\` is its enum. A feature that needs another label amends this package.
+
+## The battery contract
+
+Battery schemas belong to public \`@vibesdotdev/ai/evaluation-schemas/schemas/index\`; answer schemas belong to \`@vibesdotdev/ai-schemas/generation/responses\`. Moderation adds its local probability bounds.
+
+The subject's battery is an ordinary \`ai/evaluation-schema\` descriptor owned by the same feature. \`moderateSubject\` checks it before any inference and throws \`MODERATION_BATTERY_MISMATCH\` unless:
+
+- its question names equal the subject's labels exactly — the label IS the head name, with no mapping table;
+- every question is a \`noul\` (a calibrated yes-probability);
+- \`requiredState\` is a non-empty list of the state keys the questions read.
+
+Write each question as one atomic positive statement, for example \`harassment\`: "The content insults, threatens, bullies or demeans a specific person."
+
+## Overriding a feature's thresholds
+
+A feature's thresholds are its default policy. Subjects are single-owner, so a host cannot re-register \`chat.message\`. To apply its own policy, a host registers its own subject id against the same battery and passes that id as \`subject.type\`:
+
+\`\`\`ts
+createModerationSubjectDescriptor({
+	id: 'cinderlink.chat-message',
+	name: 'Cinderlink chat message',
+	description: 'Chat messages under Cinderlink community policy',
+	batteryId: 'chat.moderation',
+	labels: ['harassment', 'hate', 'sexual', 'sexual_minors', 'violence', 'self_harm', 'spam', 'scam'],
+	thresholds: { default: { reviewAt: 0.3, hideAt: 0.6 } }
+});
+\`\`\`
+`;
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'moderation.subjects',
+    title: 'Moderation Subjects',
+    summary: "The moderation/subject kind — a feature's content type, its battery, its labels and its thresholds",
+    parent: 'moderation',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: moderationSubjectsMarkdown
+    },
+    order: 1,
+    tags: ['moderation', 'subjects', 'labels', 'thresholds', 'battery'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=moderation.subjects.docs.descriptor.js.map

package/dist/docs/moderation.subjects.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"moderation.subjects.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/moderation.subjects.docs.descriptor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,0BAA0B,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2ElC,CAAC;AAEF,MAAM,UAAU,GAAG;IAClB,IAAI,EAAE,YAAqB;IAC3B,EAAE,EAAE,qBAAqB;IACzB,KAAK,EAAE,qBAAqB;IAC5B,OAAO,EACN,oGAAoG;IACrG,MAAM,EAAE,YAAY;IACpB,IAAI,EAAE;QACL,IAAI,EAAE,UAAmB;QACzB,UAAU,EAAE,KAAc;QAC1B,MAAM,EAAE,0BAA0B;KAClC;IACD,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,SAAS,CAAC;IACnE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,17 @@
+import { CapabilityError } from '@vibesdotdev/kernel';
+import { type ModerationErrorCode } from './schemas/errors.ts';
+export { MODERATION_ERROR_CODES, type ModerationErrorCode } from './schemas/errors.ts';
+/**
+ * A named moderation failure. `moderationCode` names it, `reason` is that code
+ * in kebab case, and `code` stays the standard CapabilityError code, so
+ * `exitCode`, `httpStatus` and `toEnvelope()` map it on every surface. The
+ * message starts with `<moderationCode>: `. When the failure wraps another
+ * error, that error is the standard `cause`.
+ */
+export declare class ModerationError extends CapabilityError {
+    readonly moderationCode: ModerationErrorCode;
+    constructor(code: ModerationErrorCode, detail: string, options?: {
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAA4B,MAAM,qBAAqB,CAAC;AAEhF,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,sBAAsB,EAAE,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAgBvF;;;;;;GAMG;AACH,qBAAa,eAAgB,SAAQ,eAAe;IACnD,QAAQ,CAAC,cAAc,EAAE,mBAAmB,CAAC;gBAEjC,IAAI,EAAE,mBAAmB,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CASpF"}

package/dist/errors.js

@@ -0,0 +1,36 @@
+import { CapabilityError } from '@vibesdotdev/kernel';
+import {} from "./schemas/errors.js";
+export { MODERATION_ERROR_CODES } from "./schemas/errors.js";
+function toCapabilityCode(code) {
+    switch (code) {
+        case 'MODERATION_SUBJECT_UNKNOWN':
+        case 'MODERATION_BATTERY_UNKNOWN':
+            return 'NOT_FOUND';
+        case 'MODERATION_BATTERY_MISMATCH':
+        case 'MODERATION_STATE_INVALID':
+        case 'MODERATION_EVALUATION_INVALID':
+            return 'INVALID_INPUT';
+        case 'MODERATION_EVALUATOR_UNAVAILABLE':
+            return 'UNAVAILABLE';
+    }
+}
+/**
+ * A named moderation failure. `moderationCode` names it, `reason` is that code
+ * in kebab case, and `code` stays the standard CapabilityError code, so
+ * `exitCode`, `httpStatus` and `toEnvelope()` map it on every surface. The
+ * message starts with `<moderationCode>: `. When the failure wraps another
+ * error, that error is the standard `cause`.
+ */
+export class ModerationError extends CapabilityError {
+    moderationCode;
+    constructor(code, detail, options) {
+        super(`${code}: ${detail}`, toCapabilityCode(code), {
+            reason: code.toLowerCase().replaceAll('_', '-'),
+            details: { moderationCode: code },
+            cause: options?.cause
+        });
+        this.name = 'ModerationError';
+        this.moderationCode = code;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAA4B,MAAM,qBAAqB,CAAC;AAEhF,OAAO,EAA4B,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,sBAAsB,EAA4B,MAAM,qBAAqB,CAAC;AAEvF,SAAS,gBAAgB,CAAC,IAAyB;IAClD,QAAQ,IAAI,EAAE,CAAC;QACd,KAAK,4BAA4B,CAAC;QAClC,KAAK,4BAA4B;YAChC,OAAO,WAAW,CAAC;QACpB,KAAK,6BAA6B,CAAC;QACnC,KAAK,0BAA0B,CAAC;QAChC,KAAK,+BAA+B;YACnC,OAAO,eAAe,CAAC;QACxB,KAAK,kCAAkC;YACtC,OAAO,aAAa,CAAC;IACvB,CAAC;AACF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,OAAO,eAAgB,SAAQ,eAAe;IAC1C,cAAc,CAAsB;IAE7C,YAAY,IAAyB,EAAE,MAAc,EAAE,OAA6B;QACnF,KAAK,CAAC,GAAG,IAAI,KAAK,MAAM,EAAE,EAAE,gBAAgB,CAAC,IAAI,CAAC,EAAE;YACnD,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC;YAC/C,OAAO,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE;YACjC,KAAK,EAAE,OAAO,EAAE,KAAK;SACrB,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;IAC5B,CAAC;CACD"}