@crowdsource.you/core 1.2.0

package/dist/defaults.d.ts

@@ -0,0 +1,61 @@
+/**
+ * What an integrator does not have to declare, and why each default is safe to
+ * apply without being asked.
+ *
+ * The product requirement is near-zero configuration: an application should be
+ * able to report a piece of content with a credential and the object itself. The
+ * plan's requirement pulling the other way is §6.4 — every decision records the
+ * policy version it was decided under, and a policy update must never silently
+ * change what a past decision meant.
+ *
+ * Both hold only if the default is a PINNED VERSION rather than "whatever is
+ * current". `DEFAULT_POLICY` below names a specific immutable published version.
+ * When CrowdSource publishes a newer baseline, this constant changes in a
+ * release of this package and integrators adopt it by upgrading — which is
+ * visible in a lockfile, reviewable in a diff, and dated. The alternative
+ * (resolving "latest" server-side) would move the policy version under an
+ * application that never changed a line, and would silently split
+ * `caseDedupKey` — §7.3 makes the policy version part of that key, so the day it
+ * moved, two reports about one post would open two cases.
+ */
+import type { CasePolicyRef, CasePrivacy, TaxonomyCode } from '@crowdsource.you/contracts';
+/** Where the service lives. One deployment; there is no sandbox host. */
+export declare const DEFAULT_BASE_URL = "https://api.crowdsource.oxy.so";
+/**
+ * The policy set a report is evaluated under when the application declares
+ * none: the baseline CrowdSource ships over its own universal taxonomy (§6.3).
+ *
+ * Must stay equal to `BASELINE_POLICY_SET_ID` / `BASELINE_POLICY_VERSION` in the
+ * backend's `modules/policy/policyBaseline.ts`, which is the registry that
+ * resolves it. A drift is not a type error and not a test failure anywhere else:
+ * it is a 422 on every zero-config report, in production, at the moment of
+ * upgrade. `__tests__/defaults.test.ts` reads that file and asserts the pair.
+ */
+export declare const DEFAULT_POLICY: CasePolicyRef;
+/**
+ * §13.6's default retention: 30 days after a final decision, configurable by
+ * policy.
+ */
+export declare const DEFAULT_RETENTION_DAYS = 30;
+/**
+ * Allegation codes that must never reach a community jury (§7.5).
+ *
+ * §7.5 routes child sexual abuse and potentially illegal material to a
+ * specialist team under legal protocol, and non-consensual intimate material to
+ * specialist review. An integrator who never read §7.5 still gets that: an
+ * envelope alleging one of these is composed with `allowCommunityReview: false`,
+ * and an application that explicitly asks for `true` alongside one of them is
+ * REFUSED rather than quietly corrected — the belief that this material can be
+ * community-reviewed is the defect, and silently fixing the field would leave
+ * the belief in place.
+ *
+ * This is a floor, never a ceiling. Triage may route a case away from the
+ * community for reasons this list cannot see; nothing here can route one
+ * towards it.
+ */
+export declare const COMMUNITY_REVIEW_FORBIDDEN_ALLEGATIONS: readonly TaxonomyCode[];
+/** The allegations in `codes` that §7.5 keeps away from a community jury. */
+export declare function allegationsForbiddingCommunityReview(codes: readonly TaxonomyCode[]): readonly TaxonomyCode[];
+/** The privacy terms of a report that declares none. */
+export declare function defaultPrivacy(allegationCodes: readonly TaxonomyCode[]): CasePrivacy;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE3F,yEAAyE;AACzE,eAAO,MAAM,gBAAgB,mCAAmC,CAAC;AAEjE;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,EAAE,aAG3B,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,sCAAsC,EAAE,SAAS,YAAY,EAMxE,CAAC;AAIH,6EAA6E;AAC7E,wBAAgB,oCAAoC,CAClD,KAAK,EAAE,SAAS,YAAY,EAAE,GAC7B,SAAS,YAAY,EAAE,CAEzB;AAED,wDAAwD;AACxD,wBAAgB,cAAc,CAAC,eAAe,EAAE,SAAS,YAAY,EAAE,GAAG,WAAW,CAKpF"}

package/dist/defaults.js

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * What an integrator does not have to declare, and why each default is safe to
+ * apply without being asked.
+ *
+ * The product requirement is near-zero configuration: an application should be
+ * able to report a piece of content with a credential and the object itself. The
+ * plan's requirement pulling the other way is §6.4 — every decision records the
+ * policy version it was decided under, and a policy update must never silently
+ * change what a past decision meant.
+ *
+ * Both hold only if the default is a PINNED VERSION rather than "whatever is
+ * current". `DEFAULT_POLICY` below names a specific immutable published version.
+ * When CrowdSource publishes a newer baseline, this constant changes in a
+ * release of this package and integrators adopt it by upgrading — which is
+ * visible in a lockfile, reviewable in a diff, and dated. The alternative
+ * (resolving "latest" server-side) would move the policy version under an
+ * application that never changed a line, and would silently split
+ * `caseDedupKey` — §7.3 makes the policy version part of that key, so the day it
+ * moved, two reports about one post would open two cases.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMMUNITY_REVIEW_FORBIDDEN_ALLEGATIONS = exports.DEFAULT_RETENTION_DAYS = exports.DEFAULT_POLICY = exports.DEFAULT_BASE_URL = void 0;
+exports.allegationsForbiddingCommunityReview = allegationsForbiddingCommunityReview;
+exports.defaultPrivacy = defaultPrivacy;
+/** Where the service lives. One deployment; there is no sandbox host. */
+exports.DEFAULT_BASE_URL = 'https://api.crowdsource.oxy.so';
+/**
+ * The policy set a report is evaluated under when the application declares
+ * none: the baseline CrowdSource ships over its own universal taxonomy (§6.3).
+ *
+ * Must stay equal to `BASELINE_POLICY_SET_ID` / `BASELINE_POLICY_VERSION` in the
+ * backend's `modules/policy/policyBaseline.ts`, which is the registry that
+ * resolves it. A drift is not a type error and not a test failure anywhere else:
+ * it is a 422 on every zero-config report, in production, at the moment of
+ * upgrade. `__tests__/defaults.test.ts` reads that file and asserts the pair.
+ */
+exports.DEFAULT_POLICY = Object.freeze({
+    policySetId: 'crowdsource.baseline',
+    version: '2026.07',
+});
+/**
+ * §13.6's default retention: 30 days after a final decision, configurable by
+ * policy.
+ */
+exports.DEFAULT_RETENTION_DAYS = 30;
+/**
+ * Allegation codes that must never reach a community jury (§7.5).
+ *
+ * §7.5 routes child sexual abuse and potentially illegal material to a
+ * specialist team under legal protocol, and non-consensual intimate material to
+ * specialist review. An integrator who never read §7.5 still gets that: an
+ * envelope alleging one of these is composed with `allowCommunityReview: false`,
+ * and an application that explicitly asks for `true` alongside one of them is
+ * REFUSED rather than quietly corrected — the belief that this material can be
+ * community-reviewed is the defect, and silently fixing the field would leave
+ * the belief in place.
+ *
+ * This is a floor, never a ceiling. Triage may route a case away from the
+ * community for reasons this list cannot see; nothing here can route one
+ * towards it.
+ */
+exports.COMMUNITY_REVIEW_FORBIDDEN_ALLEGATIONS = Object.freeze([
+    'child_safety.sexualization',
+    'child_safety.grooming',
+    'child_safety.exploitation',
+    'sexual_content.non_consensual',
+    'sexual_content.exploitation',
+]);
+const FORBIDDEN_SET = new Set(exports.COMMUNITY_REVIEW_FORBIDDEN_ALLEGATIONS);
+/** The allegations in `codes` that §7.5 keeps away from a community jury. */
+function allegationsForbiddingCommunityReview(codes) {
+    return codes.filter((code) => FORBIDDEN_SET.has(code));
+}
+/** The privacy terms of a report that declares none. */
+function defaultPrivacy(allegationCodes) {
+    return {
+        retentionDays: exports.DEFAULT_RETENTION_DAYS,
+        allowCommunityReview: allegationsForbiddingCommunityReview(allegationCodes).length === 0,
+    };
+}
+//# sourceMappingURL=defaults.js.map

package/dist/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;GAmBG;;;AAuDH,oFAIC;AAGD,wCAKC;AA/DD,yEAAyE;AAC5D,QAAA,gBAAgB,GAAG,gCAAgC,CAAC;AAEjE;;;;;;;;;GASG;AACU,QAAA,cAAc,GAAkB,MAAM,CAAC,MAAM,CAAC;IACzD,WAAW,EAAE,sBAAsB;IACnC,OAAO,EAAE,SAAS;CACnB,CAAC,CAAC;AAEH;;;GAGG;AACU,QAAA,sBAAsB,GAAG,EAAE,CAAC;AAEzC;;;;;;;;;;;;;;;GAeG;AACU,QAAA,sCAAsC,GAA4B,MAAM,CAAC,MAAM,CAAC;IAC3F,4BAA4B;IAC5B,uBAAuB;IACvB,2BAA2B;IAC3B,+BAA+B;IAC/B,6BAA6B;CAC9B,CAAC,CAAC;AAEH,MAAM,aAAa,GAAwB,IAAI,GAAG,CAAC,8CAAsC,CAAC,CAAC;AAE3F,6EAA6E;AAC7E,SAAgB,oCAAoC,CAClD,KAA8B;IAE9B,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;AACzD,CAAC;AAED,wDAAwD;AACxD,SAAgB,cAAc,CAAC,eAAwC;IACrE,OAAO;QACL,aAAa,EAAE,8BAAsB;QACrC,oBAAoB,EAAE,oCAAoC,CAAC,eAAe,CAAC,CAAC,MAAM,KAAK,CAAC;KACzF,CAAC;AACJ,CAAC"}

package/dist/digest.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Resource digests (§5.2 `sha256`, §5.6 "SHA 256 of each resource").
+ *
+ * Every inline resource in an envelope must carry a digest of "the exact
+ * representation reviewed", and asking an integrator to compute one is asking
+ * them to get canonical serialisation right — which they will do differently
+ * from the next integrator, and differently again from themselves next quarter.
+ * So the client computes it, from one rule applied to every resource type:
+ *
+ *     sha256:<hex of SHA-256 over canonicalJson({ type, data }) in UTF-8>
+ *
+ * `type` is inside the digest so a `text` resource and a `metadata` resource
+ * carrying identical fields do not produce the same digest. `custom` hashes its
+ * registered `schemaId` and `payload` for the same reason.
+ *
+ * Determinism is not a nicety here, it is the deduplication invariant. §7.3
+ * requires two people reporting the same version of the same post to land on ONE
+ * case, and the server's `caseDedupKey` is computed over a projection of the
+ * envelope that INCLUDES every resource verbatim, digest and all. A digest that
+ * varied with key order — or with which reporter sent it — would give the same
+ * post two cases, and "one penalty per incident" would be broken by a JSON
+ * serialiser.
+ *
+ * Asset-backed resources are the exception the contract already makes: their
+ * bytes live outside the envelope and `asset.sha256` is the digest of those
+ * bytes, so nothing here computes one for them.
+ */
+/** A JSON value that can be canonicalised. */
+export type CanonicalValue = string | number | boolean | null | readonly CanonicalValue[] | {
+    readonly [key: string]: CanonicalValue | undefined;
+};
+/**
+ * JSON with object keys in a fixed order and `undefined` members dropped.
+ *
+ * Array order is PRESERVED. In a conversation's `messageResourceIds` the order
+ * is the meaning, and the backend's own canonicaliser makes the same choice for
+ * the same reason.
+ */
+export declare function canonicalJson(value: CanonicalValue): string;
+/** `sha256:<64 lowercase hex>` — the only digest form the contract accepts. */
+export declare function sha256Digest(bytes: Uint8Array | string): string;
+/** The digest of an inline resource's reviewable representation. */
+export declare function resourceDigest(reviewable: CanonicalValue): string;
+//# sourceMappingURL=digest.d.ts.map

package/dist/digest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"digest.d.ts","sourceRoot":"","sources":["../src/digest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,8CAA8C;AAC9C,MAAM,MAAM,cAAc,GACtB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,cAAc,EAAE,GACzB;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAAA;CAAE,CAAC;AAE3D;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAwB3D;AAYD,+EAA+E;AAC/E,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,MAAM,CAE/D;AAED,oEAAoE;AACpE,wBAAgB,cAAc,CAAC,UAAU,EAAE,cAAc,GAAG,MAAM,CAEjE"}

package/dist/digest.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * Resource digests (§5.2 `sha256`, §5.6 "SHA 256 of each resource").
+ *
+ * Every inline resource in an envelope must carry a digest of "the exact
+ * representation reviewed", and asking an integrator to compute one is asking
+ * them to get canonical serialisation right — which they will do differently
+ * from the next integrator, and differently again from themselves next quarter.
+ * So the client computes it, from one rule applied to every resource type:
+ *
+ *     sha256:<hex of SHA-256 over canonicalJson({ type, data }) in UTF-8>
+ *
+ * `type` is inside the digest so a `text` resource and a `metadata` resource
+ * carrying identical fields do not produce the same digest. `custom` hashes its
+ * registered `schemaId` and `payload` for the same reason.
+ *
+ * Determinism is not a nicety here, it is the deduplication invariant. §7.3
+ * requires two people reporting the same version of the same post to land on ONE
+ * case, and the server's `caseDedupKey` is computed over a projection of the
+ * envelope that INCLUDES every resource verbatim, digest and all. A digest that
+ * varied with key order — or with which reporter sent it — would give the same
+ * post two cases, and "one penalty per incident" would be broken by a JSON
+ * serialiser.
+ *
+ * Asset-backed resources are the exception the contract already makes: their
+ * bytes live outside the envelope and `asset.sha256` is the digest of those
+ * bytes, so nothing here computes one for them.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalJson = canonicalJson;
+exports.sha256Digest = sha256Digest;
+exports.resourceDigest = resourceDigest;
+const node_crypto_1 = require("node:crypto");
+/**
+ * JSON with object keys in a fixed order and `undefined` members dropped.
+ *
+ * Array order is PRESERVED. In a conversation's `messageResourceIds` the order
+ * is the meaning, and the backend's own canonicaliser makes the same choice for
+ * the same reason.
+ */
+function canonicalJson(value) {
+    if (value === null || typeof value === 'boolean' || typeof value === 'string') {
+        return JSON.stringify(value);
+    }
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            throw new TypeError('A resource cannot carry a non-finite number: it has no JSON form.');
+        }
+        return JSON.stringify(value);
+    }
+    if (isCanonicalArray(value)) {
+        return `[${value.map((entry) => canonicalJson(entry)).join(',')}]`;
+    }
+    const members = Object.keys(value)
+        .sort()
+        .flatMap((key) => {
+        const member = value[key];
+        return member === undefined ? [] : [`${JSON.stringify(key)}:${canonicalJson(member)}`];
+    });
+    return `{${members.join(',')}}`;
+}
+/**
+ * A written-out predicate rather than a bare `Array.isArray`, because
+ * `Array.isArray` narrows `readonly T[]` in its TRUE branch only — the false
+ * branch keeps the array in the union and the object branch below stops
+ * type-checking.
+ */
+function isCanonicalArray(value) {
+    return Array.isArray(value);
+}
+/** `sha256:<64 lowercase hex>` — the only digest form the contract accepts. */
+function sha256Digest(bytes) {
+    return `sha256:${(0, node_crypto_1.createHash)('sha256').update(bytes).digest('hex')}`;
+}
+/** The digest of an inline resource's reviewable representation. */
+function resourceDigest(reviewable) {
+    return sha256Digest(Buffer.from(canonicalJson(reviewable), 'utf8'));
+}
+//# sourceMappingURL=digest.js.map

package/dist/digest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"digest.js","sourceRoot":"","sources":["../src/digest.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;;AAoBH,sCAwBC;AAaD,oCAEC;AAGD,wCAEC;AA9DD,6CAAyC;AAWzC;;;;;;GAMG;AACH,SAAgB,aAAa,CAAC,KAAqB;IACjD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,SAAS,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9E,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,SAAS,CAAC,mEAAmE,CAAC,CAAC;QAC3F,CAAC;QACD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IAED,IAAI,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IACrE,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC;SAC/B,IAAI,EAAE;SACN,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE;QACf,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;QAC1B,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACzF,CAAC,CAAC,CAAC;IAEL,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;AAClC,CAAC;AAED;;;;;GAKG;AACH,SAAS,gBAAgB,CAAC,KAAqB;IAC7C,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9B,CAAC;AAED,+EAA+E;AAC/E,SAAgB,YAAY,CAAC,KAA0B;IACrD,OAAO,UAAU,IAAA,wBAAU,EAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AACtE,CAAC;AAED,oEAAoE;AACpE,SAAgB,cAAc,CAAC,UAA0B;IACvD,OAAO,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;AACtE,CAAC"}

package/dist/envelope.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Composing a Case Envelope out of what an application already has.
+ *
+ * §5 is a rich document contract — resources with stable ids, relations between
+ * them, pseudonymous principal bindings, digests, a policy reference, privacy
+ * terms. Handing that to an integrator and asking them to fill it in is how a
+ * moderation integration becomes a two-week project, and it is how the parts
+ * that MATTER get filled in wrong: a random resource id or a per-report binding
+ * proof inside the hashed projection means two people reporting the same post
+ * open two cases, and "one penalty per incident" (Appendix F) fails in
+ * production with nothing failing in a test.
+ *
+ * So the integrator describes the object — its id, its author, its text, its
+ * attachments, what is alleged about it — and this module derives the rest:
+ *
+ *   * **Resource ids are positional and stable** (`res_subject`,
+ *     `res_attachment_1`, `res_context_1`). Two reporters describing the same
+ *     post through this SDK produce byte-identical resource lists, which is what
+ *     makes §7.3's dedup key match.
+ *   * **Principal refs are derived from the identity**, never generated. Same
+ *     reason: the content snapshot the server hashes includes every principal
+ *     the material points at, so a random ref would fragment the case.
+ *   * **Digests are computed** (see `digest.ts`).
+ *   * **Relations are derived** from the role each resource was given.
+ *   * **The binding proof is the Oxy `sub`.** §11.14 requires proof that a
+ *     pseudonymous ref corresponds to a real identity before anything can touch
+ *     Oxy Trust. Sign in with Oxy already produced exactly that: a subject
+ *     issued for this `applicationId`. There is no separate binding step to
+ *     implement, and this module does not invent one.
+ *   * **`applicationId` comes from the credential** (see `credential.ts`). No
+ *     input on this page can carry one.
+ */
+import { type CaseEnvelope, type CasePolicyRef, type CasePrivacy, type CaseUrgency, type MetadataBag, type PrincipalType, type Resource, type SubjectType, type TaxonomyCode } from '@crowdsource.you/contracts';
+import { CrowdSourceError } from './errors.js';
+/** `Omit` that survives a discriminated union instead of collapsing it. */
+type DistributiveOmit<T, K extends keyof never> = T extends unknown ? Omit<T, K> : never;
+/**
+ * A resource as an integrator describes it: the material, without the envelope
+ * plumbing.
+ *
+ * Derived from the published `Resource` union rather than restated, so a
+ * resource type added to the contract is available here the moment the
+ * contracts dependency is bumped, and a field removed from it stops compiling
+ * on the next build instead of being silently ignored at ingress.
+ */
+export type ResourceInput = DistributiveOmit<Resource, 'id' | 'role' | 'sha256' | 'authorPrincipalRef' | 'createdAt'> & {
+    /** The moment of the ORIGINAL object, not of the report (§5.2). */
+    readonly createdAt?: Date | string;
+};
+/** Why a context resource is attached to the subject (§5.5). */
+export type ContextRole = 'parent' | 'quoted' | 'context' | 'evidence';
+export type ContextInput = ResourceInput & {
+    readonly role: ContextRole;
+};
+/**
+ * A person or account, as the application knows them.
+ *
+ * `oxyUserId` is the OAuth `sub` from Sign in with Oxy. Supplying it is what
+ * makes an actor addressable by Oxy Trust at all — §11.14 admits no effect
+ * without a binding proof, and the `sub` issued for this application IS that
+ * proof. `id` is the application's own identifier for the same actor, for
+ * applications that keep their own user table; it is what a reviewer's
+ * pseudonymous ref is derived from and never shown to a jury.
+ */
+export interface PrincipalInput {
+    readonly oxyUserId?: string;
+    readonly id?: string;
+    /** Defaults to `oxy_user` with an `oxyUserId`, `local_user` without one. */
+    readonly type?: PrincipalType;
+}
+/** What the reporter claims, not what is true (§6.2). */
+export interface AllegationInput {
+    readonly code: TaxonomyCode;
+    /** The reporter's own words. Never shown as evidence of the claim. */
+    readonly details?: string;
+}
+export interface ReportSubjectInput {
+    /** The application's own id for the object being reported. */
+    readonly externalId: string;
+    /** §5.4, e.g. `social.post` or `custom.<organization>.<object_type>`. */
+    readonly type: SubjectType;
+    /** Where the application's own users see it. Never fetched by a jury. */
+    readonly permalink?: string;
+    readonly author?: PrincipalInput;
+}
+export interface ReportInput {
+    /** The application's own report id. Also the default idempotency key. */
+    readonly externalReportId: string;
+    readonly subject: ReportSubjectInput;
+    /** The reported material. A string is shorthand for a plain-text resource. */
+    readonly content: string | ResourceInput;
+    readonly attachments?: readonly ResourceInput[];
+    /** Replies, quotes, surrounding messages — context without extra exposure. */
+    readonly context?: readonly ContextInput[];
+    readonly allegations: readonly (TaxonomyCode | AllegationInput)[];
+    /** Who reported it. Omit for a report the application raised itself. */
+    readonly reportedBy?: PrincipalInput;
+    /** Defaults to the pinned baseline policy version — see `defaults.ts`. */
+    readonly policy?: CasePolicyRef;
+    readonly privacy?: Partial<CasePrivacy>;
+    readonly urgency?: CaseUrgency;
+    readonly metadata?: MetadataBag;
+    /**
+     * When the USER reported it (§5.1 `source.submittedAt`) — the timestamp on the
+     * application's own outbox row, not the moment of delivery.
+     *
+     * There is no default, and that is load-bearing rather than an omission. The
+     * ingress fingerprints the whole `{ externalReportId, envelope }` to detect
+     * §10.5's "external id reused with different content", so ANY value this
+     * client invented per attempt would make a legitimate retry from an outbox a
+     * permanent 409 — the failure would appear as moderation work silently
+     * stuck in a delivery queue, days after the integration was written. Omitted
+     * when absent: §5.1 makes `source` optional and §5.8 leaves it out.
+     */
+    readonly submittedAt?: Date | string;
+    /** Appendix D. Defaults to `report.<externalReportId>`. */
+    readonly idempotencyKey?: string;
+}
+/** Raised when an input cannot become a valid envelope. Never retryable. */
+export declare class CrowdSourceReportInputError extends CrowdSourceError {
+    constructor(message: string);
+}
+/** How the application declares its own environment (§5.1 `source`). */
+export type SourceEnvironment = 'production' | 'sandbox';
+export interface EnvelopeComposition {
+    readonly applicationId: string;
+    readonly environment: SourceEnvironment;
+}
+/**
+ * Composes and VALIDATES a Case Envelope.
+ *
+ * The parse at the end is not belt-and-braces. Everything above assembles a
+ * document from caller data — a subject type, a text body, an asset digest —
+ * and the contract is where a bad one is caught. Catching it here means the
+ * integrator sees the field and the reason at the call site, in their own
+ * process, instead of reading a 422 out of a delivery worker's log an hour
+ * later.
+ */
+export declare function composeCaseEnvelope(input: ReportInput, composition: EnvelopeComposition): CaseEnvelope;
+/** Appendix D: the same report re-delivered must return the same `reportId`. */
+export declare function defaultIdempotencyKey(externalReportId: string): string;
+export {};
+//# sourceMappingURL=envelope.d.ts.map

package/dist/envelope.d.ts.map

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