@openwop/openwop 1.1.2 → 1.1.3

package/dist/envelope-directive.d.ts

@@ -0,0 +1,77 @@
+/**
+ * envelopeDirective — RFC 0030 §A `reasoning`-field prompt directive synthesis.
+ *
+ * Hosts that advertise `capabilities.envelopes.reasoning.supported: true`
+ * with `promptDirective: "advisory"` or `"mandatory"` inject a system-prompt
+ * directive instructing the model to populate the OPTIONAL `reasoning` field
+ * on envelope payload schemas that carry it. The directive is informational
+ * — hosts MUST NOT reject envelopes where `reasoning` is absent regardless
+ * of `promptDirective` strength (RFC 0030 §A).
+ *
+ * The directive fires only when the envelope's `responseSchema` declares a
+ * top-level `reasoning` property. Schemas without `reasoning` (e.g.,
+ * `schema.response` per RFC 0030 §A) do NOT receive the directive.
+ *
+ * Honest separation of concerns:
+ *   - This module decides WHEN to inject (schema has `reasoning`).
+ *   - The caller decides WHETHER to inject (read `promptDirective` from
+ *     the host's discovery advertisement).
+ *   - The model decides whether to ACTUALLY populate the field (the spec
+ *     forbids rejecting envelopes where `reasoning` is absent).
+ *
+ * **Operational note on `"mandatory"`** (per RFC 0030 §A 2026-05-21
+ * amendment). Strict-output models may honor the mandatory wording
+ * literally and refuse mid-emission when reasoning would be vacuous.
+ * Hosts SHOULD prefer `"advisory"` unless empirical testing against the
+ * active model class confirms `"mandatory"` doesn't trigger refusals.
+ *
+ * @see RFCS/0030-envelope-reasoning-and-tier-one-subset.md §A
+ * @see spec/v1/ai-envelope.md §"Reasoning field (normative)"
+ */
+/**
+ * The strength of the host's `reasoning`-directive prompt injection.
+ *
+ * `"off"`      — no directive injected. Caller skips this module entirely.
+ * `"advisory"` — directive is suggestive ("populate `reasoning` with your
+ *                analytical process if the schema permits it"). The
+ *                spec-recommended default per RFC 0030 §C.
+ * `"mandatory"` — directive is firm ("you MUST populate `reasoning` before
+ *                 emitting the structured fields"). Hosts SHOULD prefer
+ *                 `"advisory"` unless model-class-specific testing shows
+ *                 `"mandatory"` is safe.
+ *
+ * Both `"advisory"` and `"mandatory"` are prompt-injection postures, NOT
+ * wire-level refusal contracts — the host accepts envelopes regardless of
+ * whether `reasoning` is populated (RFC 0030 §A normative MUST NOT).
+ */
+export type ReasoningDirectiveStrength = 'off' | 'advisory' | 'mandatory';
+/**
+ * Build the directive string to append to the system prompt, OR `null` if
+ * the schema does not declare a top-level `reasoning` property.
+ *
+ * Callers append the returned string to the existing system prompt with a
+ * separating newline. When `strength === 'off'`, callers SHOULD short-circuit
+ * before invoking this helper (returning `null` here is treated as "no
+ * applicable schema," not "directive disabled").
+ *
+ * The helper inspects only the top-level `properties.reasoning` slot.
+ * Nested `reasoning` fields (e.g., inside an `anyOf` branch's payload) are
+ * not auto-detected — vendor-kind authors who want per-branch directives
+ * synthesize their own.
+ *
+ * @example
+ * ```ts
+ * import { buildReasoningDirective } from '@openwop/openwop';
+ *
+ * const directive = buildReasoningDirective(
+ *   { type: 'object', properties: { reasoning: { type: 'string' }, ... } },
+ *   'advisory',
+ * );
+ * // directive is a string ~80 words; null when schema lacks `reasoning`
+ * const systemPrompt = [originalSystemPrompt, schemaHint, directive]
+ *   .filter((s): s is string => Boolean(s))
+ *   .join('\n\n');
+ * ```
+ */
+export declare function buildReasoningDirective(responseSchema: unknown, strength: ReasoningDirectiveStrength): string | null;
+//# sourceMappingURL=envelope-directive.d.ts.map

package/dist/envelope-directive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope-directive.d.ts","sourceRoot":"","sources":["../src/envelope-directive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,0BAA0B,GAAG,KAAK,GAAG,UAAU,GAAG,WAAW,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,uBAAuB,CACrC,cAAc,EAAE,OAAO,EACvB,QAAQ,EAAE,0BAA0B,GACnC,MAAM,GAAG,IAAI,CA6Bf"}

package/dist/envelope-directive.js

@@ -0,0 +1,89 @@
+/**
+ * envelopeDirective — RFC 0030 §A `reasoning`-field prompt directive synthesis.
+ *
+ * Hosts that advertise `capabilities.envelopes.reasoning.supported: true`
+ * with `promptDirective: "advisory"` or `"mandatory"` inject a system-prompt
+ * directive instructing the model to populate the OPTIONAL `reasoning` field
+ * on envelope payload schemas that carry it. The directive is informational
+ * — hosts MUST NOT reject envelopes where `reasoning` is absent regardless
+ * of `promptDirective` strength (RFC 0030 §A).
+ *
+ * The directive fires only when the envelope's `responseSchema` declares a
+ * top-level `reasoning` property. Schemas without `reasoning` (e.g.,
+ * `schema.response` per RFC 0030 §A) do NOT receive the directive.
+ *
+ * Honest separation of concerns:
+ *   - This module decides WHEN to inject (schema has `reasoning`).
+ *   - The caller decides WHETHER to inject (read `promptDirective` from
+ *     the host's discovery advertisement).
+ *   - The model decides whether to ACTUALLY populate the field (the spec
+ *     forbids rejecting envelopes where `reasoning` is absent).
+ *
+ * **Operational note on `"mandatory"`** (per RFC 0030 §A 2026-05-21
+ * amendment). Strict-output models may honor the mandatory wording
+ * literally and refuse mid-emission when reasoning would be vacuous.
+ * Hosts SHOULD prefer `"advisory"` unless empirical testing against the
+ * active model class confirms `"mandatory"` doesn't trigger refusals.
+ *
+ * @see RFCS/0030-envelope-reasoning-and-tier-one-subset.md §A
+ * @see spec/v1/ai-envelope.md §"Reasoning field (normative)"
+ */
+/**
+ * Build the directive string to append to the system prompt, OR `null` if
+ * the schema does not declare a top-level `reasoning` property.
+ *
+ * Callers append the returned string to the existing system prompt with a
+ * separating newline. When `strength === 'off'`, callers SHOULD short-circuit
+ * before invoking this helper (returning `null` here is treated as "no
+ * applicable schema," not "directive disabled").
+ *
+ * The helper inspects only the top-level `properties.reasoning` slot.
+ * Nested `reasoning` fields (e.g., inside an `anyOf` branch's payload) are
+ * not auto-detected — vendor-kind authors who want per-branch directives
+ * synthesize their own.
+ *
+ * @example
+ * ```ts
+ * import { buildReasoningDirective } from '@openwop/openwop';
+ *
+ * const directive = buildReasoningDirective(
+ *   { type: 'object', properties: { reasoning: { type: 'string' }, ... } },
+ *   'advisory',
+ * );
+ * // directive is a string ~80 words; null when schema lacks `reasoning`
+ * const systemPrompt = [originalSystemPrompt, schemaHint, directive]
+ *   .filter((s): s is string => Boolean(s))
+ *   .join('\n\n');
+ * ```
+ */
+export function buildReasoningDirective(responseSchema, strength) {
+    if (strength === 'off')
+        return null;
+    if (!responseSchema || typeof responseSchema !== 'object')
+        return null;
+    const schema = responseSchema;
+    const properties = schema.properties;
+    if (!properties || typeof properties !== 'object')
+        return null;
+    const reasoningProp = properties.reasoning;
+    if (!reasoningProp || typeof reasoningProp !== 'object')
+        return null;
+    if (strength === 'mandatory') {
+        return [
+            'BEFORE emitting the structured fields, populate the `reasoning` property with your analytical',
+            'process — explain how you derived each structured field, what assumptions you made, and what',
+            'risks or alternative interpretations you considered. The `reasoning` field is REQUIRED in your',
+            'output; do not skip it. (Note: the host accepts envelopes where `reasoning` is absent per',
+            'RFC 0030 §A, but for this dispatch the host expects it populated.)',
+        ].join(' ');
+    }
+    // strength === 'advisory'
+    return [
+        'If your response schema declares a `reasoning` property, populate it as the first field with',
+        'your analytical process — explain how you derived each structured field. Per Tam et al. (arXiv',
+        "2408.02442), models constrained to strict JSON output suffer reasoning-quality collapse when",
+        'no reasoning slot exists; use this field to think before emitting the structured payload. The',
+        'host accepts envelopes where `reasoning` is absent — populate it when it improves clarity.',
+    ].join(' ');
+}
+//# sourceMappingURL=envelope-directive.js.map

package/dist/envelope-directive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope-directive.js","sourceRoot":"","sources":["../src/envelope-directive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAoBH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,uBAAuB,CACrC,cAAuB,EACvB,QAAoC;IAEpC,IAAI,QAAQ,KAAK,KAAK;QAAE,OAAO,IAAI,CAAC;IACpC,IAAI,CAAC,cAAc,IAAI,OAAO,cAAc,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAEvE,MAAM,MAAM,GAAG,cAA0C,CAAC;IAC1D,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;IACrC,IAAI,CAAC,UAAU,IAAI,OAAO,UAAU,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAE/D,MAAM,aAAa,GAAI,UAAsC,CAAC,SAAS,CAAC;IACxE,IAAI,CAAC,aAAa,IAAI,OAAO,aAAa,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAErE,IAAI,QAAQ,KAAK,WAAW,EAAE,CAAC;QAC7B,OAAO;YACL,+FAA+F;YAC/F,8FAA8F;YAC9F,gGAAgG;YAChG,2FAA2F;YAC3F,oEAAoE;SACrE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACd,CAAC;IAED,0BAA0B;IAC1B,OAAO;QACL,8FAA8F;QAC9F,gGAAgG;QAChG,8FAA8F;QAC9F,+FAA+F;QAC/F,4FAA4F;KAC7F,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACd,CAAC"}

package/dist/index.d.ts

@@ -26,4 +26,8 @@ export type { VerifyWebhookSignatureOptions, VerifyWebhookOutcome, } from './web
 export { RegistryClient } from './registry-helpers.js';
 export type { RegistryClientOptions, RegistryDiscovery, RegistryIndex, RegistryIndexEntry, RegistryPackMetadata, RegistryVersionManifest, } from './registry-helpers.js';
 export type { AIEnvelope, AIEnvelopeErrorPayload, ClarificationRequestPayload, EnvelopeContract, EnvelopeContractRefusal, EnvelopeContractsCapability, EnvelopeMeta, EnvelopeOutcome, EnvelopeStrictness, PartialInfo, SchemaRequestPayload, SchemaResponsePayload, ValidationDetail, } from './types.js';
+export { buildReasoningDirective } from './envelope-directive.js';
+export type { ReasoningDirectiveStrength } from './envelope-directive.js';
+export { parseRefusal } from './parse-refusal.js';
+export type { RefusalProvider, RefusalSignal } from './parse-refusal.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,YAAY,EACV,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,EACtB,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,eAAe,EACf,WAAW,EACX,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,EACvB,0BAA0B,EAC1B,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,+BAA+B,EAC/B,uBAAuB,EACvB,wBAAwB,EACxB,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,WAAW,EACX,WAAW,EACX,SAAS,EACT,UAAU,EACV,aAAa,EACb,oBAAoB,EACpB,0BAA0B,EAC1B,sBAAsB,EACtB,wBAAwB,EACxB,mBAAmB,EACnB,mBAAmB,EAEnB,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,UAAU,EACV,SAAS,EACT,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,YAAY,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAIzE,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,cAAc,EACd,yBAAyB,GAC1B,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,uBAAuB,EACvB,WAAW,GACZ,MAAM,oBAAoB,CAAC;AAK5B,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,YAAY,EACZ,QAAQ,GACT,MAAM,kBAAkB,CAAC;AAM1B,OAAO,EACL,4BAA4B,EAC5B,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAMtE,OAAO,EACL,wCAAwC,EACxC,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,6BAA6B,EAC7B,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,YAAY,EACV,qBAAqB,EACrB,iBAAiB,EACjB,aAAa,EACb,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,uBAAuB,CAAC;AAI/B,YAAY,EACV,UAAU,EACV,sBAAsB,EACtB,2BAA2B,EAC3B,gBAAgB,EAChB,uBAAuB,EACvB,2BAA2B,EAC3B,YAAY,EACZ,eAAe,EACf,kBAAkB,EAClB,WAAW,EACX,oBAAoB,EACpB,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,YAAY,EACV,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,EACtB,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,eAAe,EACf,WAAW,EACX,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,EACvB,0BAA0B,EAC1B,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,+BAA+B,EAC/B,uBAAuB,EACvB,wBAAwB,EACxB,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,WAAW,EACX,WAAW,EACX,SAAS,EACT,UAAU,EACV,aAAa,EACb,oBAAoB,EACpB,0BAA0B,EAC1B,sBAAsB,EACtB,wBAAwB,EACxB,mBAAmB,EACnB,mBAAmB,EAEnB,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,UAAU,EACV,SAAS,EACT,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,YAAY,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAIzE,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,cAAc,EACd,yBAAyB,GAC1B,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,uBAAuB,EACvB,WAAW,GACZ,MAAM,oBAAoB,CAAC;AAK5B,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,YAAY,EACZ,QAAQ,GACT,MAAM,kBAAkB,CAAC;AAM1B,OAAO,EACL,4BAA4B,EAC5B,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAMtE,OAAO,EACL,wCAAwC,EACxC,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,6BAA6B,EAC7B,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,YAAY,EACV,qBAAqB,EACrB,iBAAiB,EACjB,aAAa,EACb,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,uBAAuB,CAAC;AAI/B,YAAY,EACV,UAAU,EACV,sBAAsB,EACtB,2BAA2B,EAC3B,gBAAgB,EAChB,uBAAuB,EACvB,2BAA2B,EAC3B,YAAY,EACZ,eAAe,EACf,kBAAkB,EAClB,WAAW,EACX,oBAAoB,EACpB,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAQpB,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAClE,YAAY,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AAW1E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -33,4 +33,21 @@ export { DEFAULT_WEBHOOK_FRESHNESS_WINDOW_SECONDS, verifyWebhookSignature, signW
 // typed client for the public node-pack registry at packs.openwop.dev
 // per spec/v1/registry-operations.md.
 export { RegistryClient } from './registry-helpers.js';
+// RFC 0030 §A `reasoning` field prompt-directive helper. Hosts that
+// advertise `capabilities.envelopes.reasoning.supported: true` use this
+// to synthesize the system-prompt fragment that instructs the model to
+// populate the OPTIONAL `reasoning` field. See `envelope-directive.ts`
+// for the operational note on `"mandatory"` strength (provider-side
+// refusal risk per the 2026-05-21 RFC 0030 amendment).
+export { buildReasoningDirective } from './envelope-directive.js';
+// RFC 0032 §B.3 + RFC 0033 §D refusal detection helper. Normalizes
+// per-provider safety-stop signals (Anthropic `stop_reason: "refusal"`,
+// OpenAI `message.refusal` + `finish_reason: "content_filter"`, Gemini
+// `finishReason: "SAFETY"` + `promptFeedback.blockReason: "SAFETY"`)
+// to a canonical `{ refusalText, safetyCategory?, provider }` shape.
+// Hosts route the non-null return through `envelope.refusal` emission
+// + the `envelope_refusal` terminal error code (RFC 0033 §F).
+// **SECURITY:** Pass `refusalText` through the BYOK redaction harness
+// BEFORE persistence — this helper does NOT redact.
+export { parseRefusal } from './parse-refusal.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAoDtC,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAGxC,2EAA2E;AAC3E,6DAA6D;AAC7D,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,cAAc,EACd,yBAAyB,GAC1B,MAAM,oBAAoB,CAAC;AAM5B,yEAAyE;AACzE,yEAAyE;AACzE,oBAAoB;AACpB,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,cAAc,GACf,MAAM,kBAAkB,CAAC;AAS1B,iDAAiD;AACjD,sEAAsE;AACtE,mEAAmE;AACnE,uDAAuD;AACvD,OAAO,EACL,4BAA4B,EAC5B,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AAG/B,sEAAsE;AACtE,4DAA4D;AAC5D,sEAAsE;AACtE,uDAAuD;AACvD,OAAO,EACL,wCAAwC,EACxC,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAM9B,uEAAuE;AACvE,sEAAsE;AACtE,sCAAsC;AACtC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAoDtC,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAGxC,2EAA2E;AAC3E,6DAA6D;AAC7D,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,cAAc,EACd,yBAAyB,GAC1B,MAAM,oBAAoB,CAAC;AAM5B,yEAAyE;AACzE,yEAAyE;AACzE,oBAAoB;AACpB,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,cAAc,GACf,MAAM,kBAAkB,CAAC;AAS1B,iDAAiD;AACjD,sEAAsE;AACtE,mEAAmE;AACnE,uDAAuD;AACvD,OAAO,EACL,4BAA4B,EAC5B,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AAG/B,sEAAsE;AACtE,4DAA4D;AAC5D,sEAAsE;AACtE,uDAAuD;AACvD,OAAO,EACL,wCAAwC,EACxC,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAM9B,uEAAuE;AACvE,sEAAsE;AACtE,sCAAsC;AACtC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AA4BvD,oEAAoE;AACpE,wEAAwE;AACxE,uEAAuE;AACvE,uEAAuE;AACvE,oEAAoE;AACpE,uDAAuD;AACvD,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAGlE,mEAAmE;AACnE,wEAAwE;AACxE,uEAAuE;AACvE,qEAAqE;AACrE,qEAAqE;AACrE,sEAAsE;AACtE,8DAA8D;AAC9D,sEAAsE;AACtE,oDAAoD;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/parse-refusal.d.ts

@@ -0,0 +1,114 @@
+/**
+ * parseRefusal — normalize per-provider LLM safety-stop signals to the
+ * canonical RFC 0032 §B.3 refusal shape.
+ *
+ * The three Tier-1 vendors (Anthropic / OpenAI / Google Gemini) surface
+ * refusals through different fields:
+ *
+ *   - **Anthropic Messages API**: `stop_reason: "refusal"` (their 2025
+ *     release) OR `stop_reason: "end_turn"` accompanied by safety-stop
+ *     markers in the content. Refusal text MAY be inline in the
+ *     `content[]` array's text blocks.
+ *   - **OpenAI Chat Completions**: `choices[0].finish_reason:
+ *     "content_filter"` OR `choices[0].message.refusal: <string>` (the
+ *     refusal-text field added in their structured-output release).
+ *   - **Google Gemini**: `candidates[0].finishReason: "SAFETY"` OR
+ *     `promptFeedback.blockReason: "SAFETY"` (input-side block).
+ *
+ * Without normalization, every host re-implements this detection. This
+ * helper consolidates the per-vendor shape-detection and returns a
+ * canonical `RefusalSignal | null` — null when the response is a
+ * normal completion (no refusal detected).
+ *
+ * Per RFC 0032 §B.3 + RFC 0033 §D, hosts MUST NOT retry on refusal
+ * (circumvention concern). Callers route the non-null return through
+ * `envelope.refusal` emission + the `envelope_refusal` terminal error
+ * code (per RFC 0033 §F).
+ *
+ * Per SECURITY/invariants.yaml §envelope-refusal-no-prompt-leak,
+ * `refusalText` MUST be passed through the host's BYOK redaction
+ * harness BEFORE persistence — this helper does NOT redact; the
+ * caller is responsible for SR-1 carry-forward.
+ *
+ * @see RFCS/0032-envelope-reliability-events.md §B.3
+ * @see RFCS/0033-envelope-completion-contract.md §D + §F
+ * @see SECURITY/invariants.yaml §envelope-refusal-no-prompt-leak
+ */
+/**
+ * Provider identifier for the matched shape. `"unknown"` is reserved
+ * for refusals matched on heuristic signals without a definitive
+ * vendor-shape match.
+ */
+export type RefusalProvider = 'anthropic' | 'openai' | 'google' | 'unknown';
+/**
+ * Canonical refusal signal. All three Tier-1 vendor shapes normalize
+ * to this form. `null` from `parseRefusal()` means "no refusal detected"
+ * (a normal completion); a non-null `RefusalSignal` means the caller
+ * SHOULD route through the RFC 0032 §B.3 refusal-emission path.
+ */
+export interface RefusalSignal {
+    /**
+     * The provider's refusal text, when surfaced. MAY be `null` even for
+     * detected refusals — Anthropic + Gemini frequently refuse without
+     * inline text (the safety filter is opaque to the model). OpenAI's
+     * `message.refusal` field is the most consistent source of human-
+     * readable refusal text.
+     *
+     * **SECURITY:** When non-null, `refusalText` MAY contain prompt
+     * content that triggered the safety filter. Callers MUST pass it
+     * through their BYOK + prompt-content redaction harness BEFORE
+     * persistence (per `envelope-refusal-no-prompt-leak` SECURITY
+     * invariant).
+     */
+    refusalText: string | null;
+    /**
+     * Provider-specific safety-category identifier, when surfaced.
+     * Examples: Gemini's safety-rating categories
+     * (`HARM_CATEGORY_HARASSMENT`, etc.), OpenAI's content-filter category,
+     * Anthropic's policy-violation tag. Hosts MAY echo this on the
+     * `envelope.refusal.safetyCategory` event field for downstream
+     * observability.
+     */
+    safetyCategory?: string;
+    /**
+     * Which provider's shape was matched. Useful for debugging
+     * cross-host integration + for hosts that want to route refusals
+     * differently per vendor (e.g., different operator notifications).
+     */
+    provider: RefusalProvider;
+}
+/**
+ * Parse a provider response into a canonical refusal signal.
+ *
+ * Returns `null` when no refusal is detected (normal completion).
+ * Returns a `RefusalSignal` when the response matches one of the
+ * three Tier-1 vendors' safety-stop shapes.
+ *
+ * Detection order: OpenAI → Anthropic → Gemini. Each detector inspects
+ * a distinctive top-level field, so cross-vendor false-positives are
+ * unlikely. A response that doesn't match any vendor shape returns
+ * `null` (hosts that route through novel providers add their own
+ * detector + fall back to this for the three known ones).
+ *
+ * @example
+ * ```ts
+ * import { parseRefusal } from '@openwop/openwop';
+ *
+ * const response = await callOpenAI({...});
+ * const refusal = parseRefusal(response);
+ * if (refusal) {
+ *   // Route through envelope.refusal emission + envelope_refusal error code.
+ *   // REMEMBER to redact refusalText through the BYOK harness before
+ *   // persistence (SECURITY invariant envelope-refusal-no-prompt-leak).
+ *   await emitEnvelopeRefusal({
+ *     refusalText: redactBYOK(refusal.refusalText),
+ *     safetyCategory: refusal.safetyCategory,
+ *     provider: refusal.provider,
+ *   });
+ *   throw new EnvelopeRefusalError(...);
+ * }
+ * // ...normal-completion handling...
+ * ```
+ */
+export declare function parseRefusal(providerResponse: unknown): RefusalSignal | null;
+//# sourceMappingURL=parse-refusal.d.ts.map

package/dist/parse-refusal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-refusal.d.ts","sourceRoot":"","sources":["../src/parse-refusal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE5E;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;;;;OAYG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAE3B;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;OAIG;IACH,QAAQ,EAAE,eAAe,CAAC;CAC3B;AA6LD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,YAAY,CAAC,gBAAgB,EAAE,OAAO,GAAG,aAAa,GAAG,IAAI,CAM5E"}

package/dist/parse-refusal.js

@@ -0,0 +1,216 @@
+/**
+ * parseRefusal — normalize per-provider LLM safety-stop signals to the
+ * canonical RFC 0032 §B.3 refusal shape.
+ *
+ * The three Tier-1 vendors (Anthropic / OpenAI / Google Gemini) surface
+ * refusals through different fields:
+ *
+ *   - **Anthropic Messages API**: `stop_reason: "refusal"` (their 2025
+ *     release) OR `stop_reason: "end_turn"` accompanied by safety-stop
+ *     markers in the content. Refusal text MAY be inline in the
+ *     `content[]` array's text blocks.
+ *   - **OpenAI Chat Completions**: `choices[0].finish_reason:
+ *     "content_filter"` OR `choices[0].message.refusal: <string>` (the
+ *     refusal-text field added in their structured-output release).
+ *   - **Google Gemini**: `candidates[0].finishReason: "SAFETY"` OR
+ *     `promptFeedback.blockReason: "SAFETY"` (input-side block).
+ *
+ * Without normalization, every host re-implements this detection. This
+ * helper consolidates the per-vendor shape-detection and returns a
+ * canonical `RefusalSignal | null` — null when the response is a
+ * normal completion (no refusal detected).
+ *
+ * Per RFC 0032 §B.3 + RFC 0033 §D, hosts MUST NOT retry on refusal
+ * (circumvention concern). Callers route the non-null return through
+ * `envelope.refusal` emission + the `envelope_refusal` terminal error
+ * code (per RFC 0033 §F).
+ *
+ * Per SECURITY/invariants.yaml §envelope-refusal-no-prompt-leak,
+ * `refusalText` MUST be passed through the host's BYOK redaction
+ * harness BEFORE persistence — this helper does NOT redact; the
+ * caller is responsible for SR-1 carry-forward.
+ *
+ * @see RFCS/0032-envelope-reliability-events.md §B.3
+ * @see RFCS/0033-envelope-completion-contract.md §D + §F
+ * @see SECURITY/invariants.yaml §envelope-refusal-no-prompt-leak
+ */
+/**
+ * Try to parse the response as OpenAI Chat Completions output.
+ *
+ * Detection: top-level `choices` array. Refusal signals:
+ *   - `choices[0].finish_reason === "content_filter"`
+ *   - `choices[0].message.refusal` is a non-empty string
+ */
+function tryParseOpenAI(response) {
+    if (!response || typeof response !== 'object')
+        return null;
+    const r = response;
+    if (!Array.isArray(r.choices) || r.choices.length === 0)
+        return null;
+    const choice = r.choices[0];
+    if (!choice || typeof choice !== 'object')
+        return null;
+    const finishReason = choice.finish_reason;
+    const message = choice.message;
+    const refusalField = message && typeof message === 'object' ? message.refusal : undefined;
+    // Primary signal: explicit refusal-text field. OpenAI's structured-output
+    // release populates this when the safety filter intervenes.
+    if (typeof refusalField === 'string' && refusalField.length > 0) {
+        return { refusalText: refusalField, provider: 'openai' };
+    }
+    // Secondary signal: finish_reason. content_filter is the canonical
+    // safety-stop value.
+    if (finishReason === 'content_filter') {
+        const text = message && typeof message === 'object' && typeof message.content === 'string'
+            ? message.content
+            : null;
+        return { refusalText: text, safetyCategory: 'content_filter', provider: 'openai' };
+    }
+    return null;
+}
+/**
+ * Try to parse the response as Anthropic Messages API output.
+ *
+ * Detection: top-level `stop_reason` field (Anthropic's distinctive
+ * marker). Refusal signals:
+ *   - `stop_reason === "refusal"` (their 2025 release)
+ *
+ * Anthropic does not surface a distinct safety-category field on
+ * refusals; the `refusal` stop_reason is the binary signal.
+ */
+function tryParseAnthropic(response) {
+    if (!response || typeof response !== 'object')
+        return null;
+    const r = response;
+    if (typeof r.stop_reason !== 'string')
+        return null;
+    if (r.stop_reason === 'refusal') {
+        // Extract refusal text from the content array (Anthropic returns an
+        // array of typed blocks; refusal text appears in `text`-type blocks).
+        let refusalText = null;
+        if (Array.isArray(r.content)) {
+            const textBlocks = [];
+            for (const block of r.content) {
+                if (block && typeof block === 'object') {
+                    const b = block;
+                    if (b.type === 'text' && typeof b.text === 'string') {
+                        textBlocks.push(b.text);
+                    }
+                }
+            }
+            if (textBlocks.length > 0)
+                refusalText = textBlocks.join('\n');
+        }
+        return { refusalText, provider: 'anthropic' };
+    }
+    return null;
+}
+/**
+ * Try to parse the response as Google Gemini `generateContent` output.
+ *
+ * Detection: top-level `candidates` array OR top-level `promptFeedback`
+ * object. Refusal signals:
+ *   - `candidates[0].finishReason === "SAFETY"` (output-side block)
+ *   - `promptFeedback.blockReason === "SAFETY"` (input-side block)
+ *
+ * Gemini surfaces safety categories on `safetyRatings[]`; this helper
+ * picks the highest-probability HIGH/MEDIUM-tier category as
+ * `safetyCategory` when available.
+ */
+function tryParseGemini(response) {
+    if (!response || typeof response !== 'object')
+        return null;
+    const r = response;
+    // Output-side safety block.
+    if (Array.isArray(r.candidates) && r.candidates.length > 0) {
+        const candidate = r.candidates[0];
+        if (candidate && typeof candidate === 'object' && candidate.finishReason === 'SAFETY') {
+            const safetyCategory = extractGeminiHighestRiskCategory(candidate.safetyRatings);
+            const result = { refusalText: null, provider: 'google' };
+            if (safetyCategory !== undefined)
+                result.safetyCategory = safetyCategory;
+            return result;
+        }
+    }
+    // Input-side safety block (Gemini rejected the prompt itself).
+    if (r.promptFeedback && typeof r.promptFeedback === 'object') {
+        const pf = r.promptFeedback;
+        if (typeof pf.blockReason === 'string' && pf.blockReason.toUpperCase().includes('SAFETY')) {
+            const safetyCategory = extractGeminiHighestRiskCategory(pf.safetyRatings);
+            const result = { refusalText: null, provider: 'google' };
+            if (safetyCategory !== undefined)
+                result.safetyCategory = safetyCategory;
+            return result;
+        }
+    }
+    return null;
+}
+/**
+ * From a Gemini `safetyRatings[]` array, return the highest-probability
+ * non-NEGLIGIBLE category identifier. Returns `undefined` when the
+ * array is absent or all ratings are NEGLIGIBLE.
+ */
+function extractGeminiHighestRiskCategory(safetyRatings) {
+    if (!Array.isArray(safetyRatings))
+        return undefined;
+    const PROBABILITY_RANK = {
+        HIGH: 3,
+        MEDIUM: 2,
+        LOW: 1,
+        NEGLIGIBLE: 0,
+    };
+    let best = null;
+    for (const rating of safetyRatings) {
+        if (!rating || typeof rating !== 'object')
+            continue;
+        const r = rating;
+        if (typeof r.category !== 'string' || typeof r.probability !== 'string')
+            continue;
+        const rank = PROBABILITY_RANK[r.probability.toUpperCase()] ?? 0;
+        if (rank === 0)
+            continue;
+        if (best === null || rank > best.rank) {
+            best = { category: r.category, rank };
+        }
+    }
+    return best?.category;
+}
+/**
+ * Parse a provider response into a canonical refusal signal.
+ *
+ * Returns `null` when no refusal is detected (normal completion).
+ * Returns a `RefusalSignal` when the response matches one of the
+ * three Tier-1 vendors' safety-stop shapes.
+ *
+ * Detection order: OpenAI → Anthropic → Gemini. Each detector inspects
+ * a distinctive top-level field, so cross-vendor false-positives are
+ * unlikely. A response that doesn't match any vendor shape returns
+ * `null` (hosts that route through novel providers add their own
+ * detector + fall back to this for the three known ones).
+ *
+ * @example
+ * ```ts
+ * import { parseRefusal } from '@openwop/openwop';
+ *
+ * const response = await callOpenAI({...});
+ * const refusal = parseRefusal(response);
+ * if (refusal) {
+ *   // Route through envelope.refusal emission + envelope_refusal error code.
+ *   // REMEMBER to redact refusalText through the BYOK harness before
+ *   // persistence (SECURITY invariant envelope-refusal-no-prompt-leak).
+ *   await emitEnvelopeRefusal({
+ *     refusalText: redactBYOK(refusal.refusalText),
+ *     safetyCategory: refusal.safetyCategory,
+ *     provider: refusal.provider,
+ *   });
+ *   throw new EnvelopeRefusalError(...);
+ * }
+ * // ...normal-completion handling...
+ * ```
+ */
+export function parseRefusal(providerResponse) {
+    return (tryParseOpenAI(providerResponse) ??
+        tryParseAnthropic(providerResponse) ??
+        tryParseGemini(providerResponse));
+}
+//# sourceMappingURL=parse-refusal.js.map

package/dist/parse-refusal.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openwop/openwop",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "Production-ready TypeScript reference SDK for OpenWOP v1.0 compliant servers.",
   "repository": {
     "type": "git",

package/src/envelope-directive.ts

@@ -0,0 +1,110 @@
+/**
+ * envelopeDirective — RFC 0030 §A `reasoning`-field prompt directive synthesis.
+ *
+ * Hosts that advertise `capabilities.envelopes.reasoning.supported: true`
+ * with `promptDirective: "advisory"` or `"mandatory"` inject a system-prompt
+ * directive instructing the model to populate the OPTIONAL `reasoning` field
+ * on envelope payload schemas that carry it. The directive is informational
+ * — hosts MUST NOT reject envelopes where `reasoning` is absent regardless
+ * of `promptDirective` strength (RFC 0030 §A).
+ *
+ * The directive fires only when the envelope's `responseSchema` declares a
+ * top-level `reasoning` property. Schemas without `reasoning` (e.g.,
+ * `schema.response` per RFC 0030 §A) do NOT receive the directive.
+ *
+ * Honest separation of concerns:
+ *   - This module decides WHEN to inject (schema has `reasoning`).
+ *   - The caller decides WHETHER to inject (read `promptDirective` from
+ *     the host's discovery advertisement).
+ *   - The model decides whether to ACTUALLY populate the field (the spec
+ *     forbids rejecting envelopes where `reasoning` is absent).
+ *
+ * **Operational note on `"mandatory"`** (per RFC 0030 §A 2026-05-21
+ * amendment). Strict-output models may honor the mandatory wording
+ * literally and refuse mid-emission when reasoning would be vacuous.
+ * Hosts SHOULD prefer `"advisory"` unless empirical testing against the
+ * active model class confirms `"mandatory"` doesn't trigger refusals.
+ *
+ * @see RFCS/0030-envelope-reasoning-and-tier-one-subset.md §A
+ * @see spec/v1/ai-envelope.md §"Reasoning field (normative)"
+ */
+
+/**
+ * The strength of the host's `reasoning`-directive prompt injection.
+ *
+ * `"off"`      — no directive injected. Caller skips this module entirely.
+ * `"advisory"` — directive is suggestive ("populate `reasoning` with your
+ *                analytical process if the schema permits it"). The
+ *                spec-recommended default per RFC 0030 §C.
+ * `"mandatory"` — directive is firm ("you MUST populate `reasoning` before
+ *                 emitting the structured fields"). Hosts SHOULD prefer
+ *                 `"advisory"` unless model-class-specific testing shows
+ *                 `"mandatory"` is safe.
+ *
+ * Both `"advisory"` and `"mandatory"` are prompt-injection postures, NOT
+ * wire-level refusal contracts — the host accepts envelopes regardless of
+ * whether `reasoning` is populated (RFC 0030 §A normative MUST NOT).
+ */
+export type ReasoningDirectiveStrength = 'off' | 'advisory' | 'mandatory';
+
+/**
+ * Build the directive string to append to the system prompt, OR `null` if
+ * the schema does not declare a top-level `reasoning` property.
+ *
+ * Callers append the returned string to the existing system prompt with a
+ * separating newline. When `strength === 'off'`, callers SHOULD short-circuit
+ * before invoking this helper (returning `null` here is treated as "no
+ * applicable schema," not "directive disabled").
+ *
+ * The helper inspects only the top-level `properties.reasoning` slot.
+ * Nested `reasoning` fields (e.g., inside an `anyOf` branch's payload) are
+ * not auto-detected — vendor-kind authors who want per-branch directives
+ * synthesize their own.
+ *
+ * @example
+ * ```ts
+ * import { buildReasoningDirective } from '@openwop/openwop';
+ *
+ * const directive = buildReasoningDirective(
+ *   { type: 'object', properties: { reasoning: { type: 'string' }, ... } },
+ *   'advisory',
+ * );
+ * // directive is a string ~80 words; null when schema lacks `reasoning`
+ * const systemPrompt = [originalSystemPrompt, schemaHint, directive]
+ *   .filter((s): s is string => Boolean(s))
+ *   .join('\n\n');
+ * ```
+ */
+export function buildReasoningDirective(
+  responseSchema: unknown,
+  strength: ReasoningDirectiveStrength,
+): string | null {
+  if (strength === 'off') return null;
+  if (!responseSchema || typeof responseSchema !== 'object') return null;
+
+  const schema = responseSchema as { properties?: unknown };
+  const properties = schema.properties;
+  if (!properties || typeof properties !== 'object') return null;
+
+  const reasoningProp = (properties as { reasoning?: unknown }).reasoning;
+  if (!reasoningProp || typeof reasoningProp !== 'object') return null;
+
+  if (strength === 'mandatory') {
+    return [
+      'BEFORE emitting the structured fields, populate the `reasoning` property with your analytical',
+      'process — explain how you derived each structured field, what assumptions you made, and what',
+      'risks or alternative interpretations you considered. The `reasoning` field is REQUIRED in your',
+      'output; do not skip it. (Note: the host accepts envelopes where `reasoning` is absent per',
+      'RFC 0030 §A, but for this dispatch the host expects it populated.)',
+    ].join(' ');
+  }
+
+  // strength === 'advisory'
+  return [
+    'If your response schema declares a `reasoning` property, populate it as the first field with',
+    'your analytical process — explain how you derived each structured field. Per Tam et al. (arXiv',
+    "2408.02442), models constrained to strict JSON output suffer reasoning-quality collapse when",
+    'no reasoning slot exists; use this field to think before emitting the structured payload. The',
+    'host accepts envelopes where `reasoning` is absent — populate it when it improves clarity.',
+  ].join(' ');
+}

package/src/index.ts

@@ -157,3 +157,24 @@ export type {
   SchemaResponsePayload,
   ValidationDetail,
 } from './types.js';
+
+// RFC 0030 §A `reasoning` field prompt-directive helper. Hosts that
+// advertise `capabilities.envelopes.reasoning.supported: true` use this
+// to synthesize the system-prompt fragment that instructs the model to
+// populate the OPTIONAL `reasoning` field. See `envelope-directive.ts`
+// for the operational note on `"mandatory"` strength (provider-side
+// refusal risk per the 2026-05-21 RFC 0030 amendment).
+export { buildReasoningDirective } from './envelope-directive.js';
+export type { ReasoningDirectiveStrength } from './envelope-directive.js';
+
+// RFC 0032 §B.3 + RFC 0033 §D refusal detection helper. Normalizes
+// per-provider safety-stop signals (Anthropic `stop_reason: "refusal"`,
+// OpenAI `message.refusal` + `finish_reason: "content_filter"`, Gemini
+// `finishReason: "SAFETY"` + `promptFeedback.blockReason: "SAFETY"`)
+// to a canonical `{ refusalText, safetyCategory?, provider }` shape.
+// Hosts route the non-null return through `envelope.refusal` emission
+// + the `envelope_refusal` terminal error code (RFC 0033 §F).
+// **SECURITY:** Pass `refusalText` through the BYOK redaction harness
+// BEFORE persistence — this helper does NOT redact.
+export { parseRefusal } from './parse-refusal.js';
+export type { RefusalProvider, RefusalSignal } from './parse-refusal.js';

package/src/parse-refusal.ts

@@ -0,0 +1,311 @@
+/**
+ * parseRefusal — normalize per-provider LLM safety-stop signals to the
+ * canonical RFC 0032 §B.3 refusal shape.
+ *
+ * The three Tier-1 vendors (Anthropic / OpenAI / Google Gemini) surface
+ * refusals through different fields:
+ *
+ *   - **Anthropic Messages API**: `stop_reason: "refusal"` (their 2025
+ *     release) OR `stop_reason: "end_turn"` accompanied by safety-stop
+ *     markers in the content. Refusal text MAY be inline in the
+ *     `content[]` array's text blocks.
+ *   - **OpenAI Chat Completions**: `choices[0].finish_reason:
+ *     "content_filter"` OR `choices[0].message.refusal: <string>` (the
+ *     refusal-text field added in their structured-output release).
+ *   - **Google Gemini**: `candidates[0].finishReason: "SAFETY"` OR
+ *     `promptFeedback.blockReason: "SAFETY"` (input-side block).
+ *
+ * Without normalization, every host re-implements this detection. This
+ * helper consolidates the per-vendor shape-detection and returns a
+ * canonical `RefusalSignal | null` — null when the response is a
+ * normal completion (no refusal detected).
+ *
+ * Per RFC 0032 §B.3 + RFC 0033 §D, hosts MUST NOT retry on refusal
+ * (circumvention concern). Callers route the non-null return through
+ * `envelope.refusal` emission + the `envelope_refusal` terminal error
+ * code (per RFC 0033 §F).
+ *
+ * Per SECURITY/invariants.yaml §envelope-refusal-no-prompt-leak,
+ * `refusalText` MUST be passed through the host's BYOK redaction
+ * harness BEFORE persistence — this helper does NOT redact; the
+ * caller is responsible for SR-1 carry-forward.
+ *
+ * @see RFCS/0032-envelope-reliability-events.md §B.3
+ * @see RFCS/0033-envelope-completion-contract.md §D + §F
+ * @see SECURITY/invariants.yaml §envelope-refusal-no-prompt-leak
+ */
+
+/**
+ * Provider identifier for the matched shape. `"unknown"` is reserved
+ * for refusals matched on heuristic signals without a definitive
+ * vendor-shape match.
+ */
+export type RefusalProvider = 'anthropic' | 'openai' | 'google' | 'unknown';
+
+/**
+ * Canonical refusal signal. All three Tier-1 vendor shapes normalize
+ * to this form. `null` from `parseRefusal()` means "no refusal detected"
+ * (a normal completion); a non-null `RefusalSignal` means the caller
+ * SHOULD route through the RFC 0032 §B.3 refusal-emission path.
+ */
+export interface RefusalSignal {
+  /**
+   * The provider's refusal text, when surfaced. MAY be `null` even for
+   * detected refusals — Anthropic + Gemini frequently refuse without
+   * inline text (the safety filter is opaque to the model). OpenAI's
+   * `message.refusal` field is the most consistent source of human-
+   * readable refusal text.
+   *
+   * **SECURITY:** When non-null, `refusalText` MAY contain prompt
+   * content that triggered the safety filter. Callers MUST pass it
+   * through their BYOK + prompt-content redaction harness BEFORE
+   * persistence (per `envelope-refusal-no-prompt-leak` SECURITY
+   * invariant).
+   */
+  refusalText: string | null;
+
+  /**
+   * Provider-specific safety-category identifier, when surfaced.
+   * Examples: Gemini's safety-rating categories
+   * (`HARM_CATEGORY_HARASSMENT`, etc.), OpenAI's content-filter category,
+   * Anthropic's policy-violation tag. Hosts MAY echo this on the
+   * `envelope.refusal.safetyCategory` event field for downstream
+   * observability.
+   */
+  safetyCategory?: string;
+
+  /**
+   * Which provider's shape was matched. Useful for debugging
+   * cross-host integration + for hosts that want to route refusals
+   * differently per vendor (e.g., different operator notifications).
+   */
+  provider: RefusalProvider;
+}
+
+interface OpenAIChoiceMessage {
+  refusal?: unknown;
+  content?: unknown;
+}
+
+interface OpenAIChoice {
+  finish_reason?: unknown;
+  message?: unknown;
+}
+
+interface OpenAIResponse {
+  choices?: unknown;
+}
+
+interface AnthropicTextBlock {
+  type?: unknown;
+  text?: unknown;
+}
+
+interface AnthropicResponse {
+  stop_reason?: unknown;
+  content?: unknown;
+}
+
+interface GeminiSafetyRating {
+  category?: unknown;
+  probability?: unknown;
+}
+
+interface GeminiCandidate {
+  finishReason?: unknown;
+  safetyRatings?: unknown;
+  content?: unknown;
+}
+
+interface GeminiPromptFeedback {
+  blockReason?: unknown;
+  safetyRatings?: unknown;
+}
+
+interface GeminiResponse {
+  candidates?: unknown;
+  promptFeedback?: unknown;
+}
+
+/**
+ * Try to parse the response as OpenAI Chat Completions output.
+ *
+ * Detection: top-level `choices` array. Refusal signals:
+ *   - `choices[0].finish_reason === "content_filter"`
+ *   - `choices[0].message.refusal` is a non-empty string
+ */
+function tryParseOpenAI(response: unknown): RefusalSignal | null {
+  if (!response || typeof response !== 'object') return null;
+  const r = response as OpenAIResponse;
+  if (!Array.isArray(r.choices) || r.choices.length === 0) return null;
+  const choice = r.choices[0] as OpenAIChoice;
+  if (!choice || typeof choice !== 'object') return null;
+
+  const finishReason = choice.finish_reason;
+  const message = choice.message as OpenAIChoiceMessage | undefined;
+  const refusalField = message && typeof message === 'object' ? message.refusal : undefined;
+
+  // Primary signal: explicit refusal-text field. OpenAI's structured-output
+  // release populates this when the safety filter intervenes.
+  if (typeof refusalField === 'string' && refusalField.length > 0) {
+    return { refusalText: refusalField, provider: 'openai' };
+  }
+
+  // Secondary signal: finish_reason. content_filter is the canonical
+  // safety-stop value.
+  if (finishReason === 'content_filter') {
+    const text =
+      message && typeof message === 'object' && typeof message.content === 'string'
+        ? message.content
+        : null;
+    return { refusalText: text, safetyCategory: 'content_filter', provider: 'openai' };
+  }
+
+  return null;
+}
+
+/**
+ * Try to parse the response as Anthropic Messages API output.
+ *
+ * Detection: top-level `stop_reason` field (Anthropic's distinctive
+ * marker). Refusal signals:
+ *   - `stop_reason === "refusal"` (their 2025 release)
+ *
+ * Anthropic does not surface a distinct safety-category field on
+ * refusals; the `refusal` stop_reason is the binary signal.
+ */
+function tryParseAnthropic(response: unknown): RefusalSignal | null {
+  if (!response || typeof response !== 'object') return null;
+  const r = response as AnthropicResponse;
+  if (typeof r.stop_reason !== 'string') return null;
+
+  if (r.stop_reason === 'refusal') {
+    // Extract refusal text from the content array (Anthropic returns an
+    // array of typed blocks; refusal text appears in `text`-type blocks).
+    let refusalText: string | null = null;
+    if (Array.isArray(r.content)) {
+      const textBlocks: string[] = [];
+      for (const block of r.content) {
+        if (block && typeof block === 'object') {
+          const b = block as AnthropicTextBlock;
+          if (b.type === 'text' && typeof b.text === 'string') {
+            textBlocks.push(b.text);
+          }
+        }
+      }
+      if (textBlocks.length > 0) refusalText = textBlocks.join('\n');
+    }
+    return { refusalText, provider: 'anthropic' };
+  }
+
+  return null;
+}
+
+/**
+ * Try to parse the response as Google Gemini `generateContent` output.
+ *
+ * Detection: top-level `candidates` array OR top-level `promptFeedback`
+ * object. Refusal signals:
+ *   - `candidates[0].finishReason === "SAFETY"` (output-side block)
+ *   - `promptFeedback.blockReason === "SAFETY"` (input-side block)
+ *
+ * Gemini surfaces safety categories on `safetyRatings[]`; this helper
+ * picks the highest-probability HIGH/MEDIUM-tier category as
+ * `safetyCategory` when available.
+ */
+function tryParseGemini(response: unknown): RefusalSignal | null {
+  if (!response || typeof response !== 'object') return null;
+  const r = response as GeminiResponse;
+
+  // Output-side safety block.
+  if (Array.isArray(r.candidates) && r.candidates.length > 0) {
+    const candidate = r.candidates[0] as GeminiCandidate;
+    if (candidate && typeof candidate === 'object' && candidate.finishReason === 'SAFETY') {
+      const safetyCategory = extractGeminiHighestRiskCategory(candidate.safetyRatings);
+      const result: RefusalSignal = { refusalText: null, provider: 'google' };
+      if (safetyCategory !== undefined) result.safetyCategory = safetyCategory;
+      return result;
+    }
+  }
+
+  // Input-side safety block (Gemini rejected the prompt itself).
+  if (r.promptFeedback && typeof r.promptFeedback === 'object') {
+    const pf = r.promptFeedback as GeminiPromptFeedback;
+    if (typeof pf.blockReason === 'string' && pf.blockReason.toUpperCase().includes('SAFETY')) {
+      const safetyCategory = extractGeminiHighestRiskCategory(pf.safetyRatings);
+      const result: RefusalSignal = { refusalText: null, provider: 'google' };
+      if (safetyCategory !== undefined) result.safetyCategory = safetyCategory;
+      return result;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * From a Gemini `safetyRatings[]` array, return the highest-probability
+ * non-NEGLIGIBLE category identifier. Returns `undefined` when the
+ * array is absent or all ratings are NEGLIGIBLE.
+ */
+function extractGeminiHighestRiskCategory(safetyRatings: unknown): string | undefined {
+  if (!Array.isArray(safetyRatings)) return undefined;
+  const PROBABILITY_RANK: Record<string, number> = {
+    HIGH: 3,
+    MEDIUM: 2,
+    LOW: 1,
+    NEGLIGIBLE: 0,
+  };
+  let best: { category: string; rank: number } | null = null;
+  for (const rating of safetyRatings) {
+    if (!rating || typeof rating !== 'object') continue;
+    const r = rating as GeminiSafetyRating;
+    if (typeof r.category !== 'string' || typeof r.probability !== 'string') continue;
+    const rank = PROBABILITY_RANK[r.probability.toUpperCase()] ?? 0;
+    if (rank === 0) continue;
+    if (best === null || rank > best.rank) {
+      best = { category: r.category, rank };
+    }
+  }
+  return best?.category;
+}
+
+/**
+ * Parse a provider response into a canonical refusal signal.
+ *
+ * Returns `null` when no refusal is detected (normal completion).
+ * Returns a `RefusalSignal` when the response matches one of the
+ * three Tier-1 vendors' safety-stop shapes.
+ *
+ * Detection order: OpenAI → Anthropic → Gemini. Each detector inspects
+ * a distinctive top-level field, so cross-vendor false-positives are
+ * unlikely. A response that doesn't match any vendor shape returns
+ * `null` (hosts that route through novel providers add their own
+ * detector + fall back to this for the three known ones).
+ *
+ * @example
+ * ```ts
+ * import { parseRefusal } from '@openwop/openwop';
+ *
+ * const response = await callOpenAI({...});
+ * const refusal = parseRefusal(response);
+ * if (refusal) {
+ *   // Route through envelope.refusal emission + envelope_refusal error code.
+ *   // REMEMBER to redact refusalText through the BYOK harness before
+ *   // persistence (SECURITY invariant envelope-refusal-no-prompt-leak).
+ *   await emitEnvelopeRefusal({
+ *     refusalText: redactBYOK(refusal.refusalText),
+ *     safetyCategory: refusal.safetyCategory,
+ *     provider: refusal.provider,
+ *   });
+ *   throw new EnvelopeRefusalError(...);
+ * }
+ * // ...normal-completion handling...
+ * ```
+ */
+export function parseRefusal(providerResponse: unknown): RefusalSignal | null {
+  return (
+    tryParseOpenAI(providerResponse) ??
+    tryParseAnthropic(providerResponse) ??
+    tryParseGemini(providerResponse)
+  );
+}