@vixor/contracts 0.2.0 → 0.2.1

package/README.md

@@ -1,37 +1,37 @@
-# @vixor/contracts
-
-Zero-runtime-dependency TypeScript contracts for VIXOR integration boundaries.
-
-## Install
-
-```sh
-npm install @vixor/contracts
-```
-
-## Runtime
-
-Node.js 20 or newer is supported. The published package contains compiled
-ES modules and TypeScript declaration files under `dist/`; consumers do not
-need a TypeScript runtime loader.
-
-## Example
-
-```ts
-import { validateEnvelope, validateOpportunityPayload, fixtureEnvelope } from "@vixor/contracts";
-
-const result = validateEnvelope(fixtureEnvelope(), validateOpportunityPayload);
-if (!result.ok) throw new Error(result.errors.join("; "));
-```
-
-Package SemVer (currently 0.2.0) is independent of the wire `SCHEMA_VERSION`
-(currently `0.1`). Consumers must validate the wire schema version independently.
-
-This package validates VIXOR event envelopes, opportunity payloads, Shield risk
-assessments, and publication candidates. It does not authenticate requests,
-verify HMAC signatures, authorize channels, or replace persistence/idempotency.
-
-## License
-
-The package is published with `UNLICENSED` metadata. Public npm visibility makes
-the artifact downloadable; it does not grant third-party rights to reuse or
-redistribute the code. Obtain separate written permission before external reuse.
+# @vixor/contracts
+
+Zero-runtime-dependency TypeScript contracts for VIXOR integration boundaries.
+
+## Install
+
+```sh
+npm install @vixor/contracts
+```
+
+## Runtime
+
+Node.js 20 or newer is supported. The published package contains compiled
+ES modules and TypeScript declaration files under `dist/`; consumers do not
+need a TypeScript runtime loader.
+
+## Example
+
+```ts
+import { validateEnvelope, validateOpportunityPayload, fixtureEnvelope } from "@vixor/contracts";
+
+const result = validateEnvelope(fixtureEnvelope(), validateOpportunityPayload);
+if (!result.ok) throw new Error(result.errors.join("; "));
+```
+
+Package SemVer (currently 0.2.1) is independent of the wire `SCHEMA_VERSION`
+(currently `0.1`). Consumers must validate the wire schema version independently.
+
+This package validates VIXOR event envelopes, opportunity payloads, Shield risk
+assessments, and publication candidates. It does not authenticate requests,
+verify HMAC signatures, authorize channels, or replace persistence/idempotency.
+
+## License
+
+The package is published with `UNLICENSED` metadata. Public npm visibility makes
+the artifact downloadable; it does not grant third-party rights to reuse or
+redistribute the code. Obtain separate written permission before external reuse.

package/dist/envelope.d.ts

@@ -0,0 +1,27 @@
+import { type ValidationResult } from "./validate.ts";
+/** Contract version — consumers must reject unsupported versions. */
+export declare const SCHEMA_VERSION = "0.1";
+export declare const PRODUCED_BY: readonly ["hunt", "shield", "core", "trade", "tg-content-bot"];
+export type ProducedBy = (typeof PRODUCED_BY)[number];
+/** The only event type on the minimal proof path (§2). */
+export declare const EVENT_OPPORTUNITY_DETECTED = "opportunity.detected";
+export interface EventEnvelope<P = unknown> {
+    schema_version: string;
+    event_id: string;
+    event_type: string;
+    occurred_at: string;
+    produced_by: ProducedBy;
+    correlation_id: string;
+    idempotency_key: string;
+    payload: P;
+}
+export interface EnvelopeOptions {
+    /** Restrict `event_type`; defaults to the minimal-path event only. */
+    allowedEventTypes?: readonly string[];
+}
+/**
+ * Validate a §1 envelope. `validatePayload` validates the event-specific
+ * payload against its schema (e.g. §2 opportunity). Envelope identity fields
+ * are length-capped for log hygiene.
+ */
+export declare function validateEnvelope<P>(raw: unknown, validatePayload: (payload: unknown) => ValidationResult<P>, opts?: EnvelopeOptions): ValidationResult<EventEnvelope<P>>;

package/dist/envelope.js

@@ -0,0 +1,68 @@
+// ============================================================================
+// VIXOR Contracts — §1 Common envelope (VIXOR_INTEGRATION_CONTRACTS_DRAFT §1)
+// ============================================================================
+import { cappedId, cappedTimestamp, field, invalid, isOneOf, isRecord, } from "./validate.js";
+/** Contract version — consumers must reject unsupported versions. */
+export const SCHEMA_VERSION = "0.1";
+export const PRODUCED_BY = [
+    "hunt",
+    "shield",
+    "core",
+    "trade",
+    "tg-content-bot",
+];
+/** The only event type on the minimal proof path (§2). */
+export const EVENT_OPPORTUNITY_DETECTED = "opportunity.detected";
+/**
+ * Validate a §1 envelope. `validatePayload` validates the event-specific
+ * payload against its schema (e.g. §2 opportunity). Envelope identity fields
+ * are length-capped for log hygiene.
+ */
+export function validateEnvelope(raw, validatePayload, opts = {}) {
+    if (!isRecord(raw))
+        return invalid("envelope: must be a JSON object");
+    const sv = field(raw, "schema_version", (v) => v === SCHEMA_VERSION
+        ? { ok: true, value: SCHEMA_VERSION }
+        : { ok: false, errors: [`schema_version: unsupported version (expected "${SCHEMA_VERSION}")`] });
+    if (!sv.ok)
+        return sv;
+    const allowed = opts.allowedEventTypes ?? [EVENT_OPPORTUNITY_DETECTED];
+    const eventId = field(raw, "event_id", (v) => cappedId(v, "event_id"));
+    if (!eventId.ok)
+        return eventId;
+    const eventType = field(raw, "event_type", (v) => isOneOf(v, allowed)
+        ? { ok: true, value: v }
+        : { ok: false, errors: [`event_type: unknown event type "${String(v).slice(0, 50)}"`] });
+    if (!eventType.ok)
+        return eventType;
+    const occurredAt = field(raw, "occurred_at", (v) => cappedTimestamp(v, "occurred_at"));
+    if (!occurredAt.ok)
+        return occurredAt;
+    const producedBy = field(raw, "produced_by", (v) => isOneOf(v, PRODUCED_BY)
+        ? { ok: true, value: v }
+        : { ok: false, errors: ["produced_by: must be one of hunt|shield|core|trade|tg-content-bot"] });
+    if (!producedBy.ok)
+        return producedBy;
+    const correlationId = field(raw, "correlation_id", (v) => cappedId(v, "correlation_id"));
+    if (!correlationId.ok)
+        return correlationId;
+    const idempotencyKey = field(raw, "idempotency_key", (v) => cappedId(v, "idempotency_key"));
+    if (!idempotencyKey.ok)
+        return idempotencyKey;
+    const payload = validatePayload(raw.payload);
+    if (!payload.ok)
+        return payload;
+    return {
+        ok: true,
+        value: {
+            schema_version: sv.value,
+            event_id: eventId.value,
+            event_type: eventType.value,
+            occurred_at: occurredAt.value,
+            produced_by: producedBy.value,
+            correlation_id: correlationId.value,
+            idempotency_key: idempotencyKey.value,
+            payload: payload.value,
+        },
+    };
+}

package/dist/fixtures.d.ts

@@ -0,0 +1,25 @@
+import type { EventEnvelope } from "./envelope.ts";
+import type { OpportunityPayload } from "./opportunity.ts";
+import type { RiskAssessment } from "./risk.ts";
+import type { PublicationCandidate } from "./publication.ts";
+/**
+ * All fixture values are constant (no Date.now, no randomness) so that two
+ * runs always produce deep-equal output and identical idempotency keys —
+ * the property T2 (duplicate → 409) depends on.
+ */
+export declare const FIXTURE_EVENT_ID = "evt-e2e-test-0001";
+export declare const FIXTURE_CORRELATION_ID = "corr-e2e-test-0001";
+export declare const FIXTURE_OPPORTUNITY_ID = "vixor-e2e-test-001";
+export declare const FIXTURE_ASSESSMENT_ID = "asmt-e2e-test-0001";
+export declare const FIXTURE_PUBLICATION_ID = "pub-e2e-test-0001";
+/** Fixed instants (UTC) — far future expiry keeps fixtures time-stable. */
+export declare const FIXTURE_OCCURRED_AT = "2026-01-01T00:00:00.000Z";
+export declare const FIXTURE_OBSERVED_AT = "2026-01-01T00:00:00.000Z";
+export declare const FIXTURE_CHECKED_AT = "2026-01-01T00:01:00.000Z";
+export declare const FIXTURE_EXPIRES_AT = "2099-01-01T00:00:00.000Z";
+/** Canonical asset identity: chain:address (Solana test fixture). */
+export declare const FIXTURE_ASSET_ID = "solana:So11111111111111111111111111111111111111112";
+export declare function fixtureOpportunityPayload(): OpportunityPayload;
+export declare function fixtureRiskAssessment(): RiskAssessment;
+export declare function fixtureEnvelope(): EventEnvelope<OpportunityPayload>;
+export declare function fixturePublicationCandidate(): PublicationCandidate;

package/dist/fixtures.js

@@ -0,0 +1,81 @@
+// ============================================================================
+// VIXOR Contracts — deterministic fixtures (M1 acceptance: one fixture
+// traverses every schema: envelope → opportunity → risk → publication)
+// ============================================================================
+import { EVENT_OPPORTUNITY_DETECTED } from "./envelope.js";
+/**
+ * All fixture values are constant (no Date.now, no randomness) so that two
+ * runs always produce deep-equal output and identical idempotency keys —
+ * the property T2 (duplicate → 409) depends on.
+ */
+export const FIXTURE_EVENT_ID = "evt-e2e-test-0001";
+export const FIXTURE_CORRELATION_ID = "corr-e2e-test-0001";
+export const FIXTURE_OPPORTUNITY_ID = "vixor-e2e-test-001";
+export const FIXTURE_ASSESSMENT_ID = "asmt-e2e-test-0001";
+export const FIXTURE_PUBLICATION_ID = "pub-e2e-test-0001";
+/** Fixed instants (UTC) — far future expiry keeps fixtures time-stable. */
+export const FIXTURE_OCCURRED_AT = "2026-01-01T00:00:00.000Z";
+export const FIXTURE_OBSERVED_AT = "2026-01-01T00:00:00.000Z";
+export const FIXTURE_CHECKED_AT = "2026-01-01T00:01:00.000Z";
+export const FIXTURE_EXPIRES_AT = "2099-01-01T00:00:00.000Z";
+/** Canonical asset identity: chain:address (Solana test fixture). */
+export const FIXTURE_ASSET_ID = "solana:So11111111111111111111111111111111111111112";
+export function fixtureOpportunityPayload() {
+    return {
+        opportunity_id: FIXTURE_OPPORTUNITY_ID,
+        asset_id: FIXTURE_ASSET_ID,
+        symbol: "TEST",
+        source: { name: "dexscreener", record_ref: "pair:e2e-test-pair-001" },
+        observed_at: FIXTURE_OBSERVED_AT,
+        market_data: {
+            liq_usd: { value: 25000, currency: "USD", at: FIXTURE_OBSERVED_AT },
+            accel_score: { value: 78, at: FIXTURE_OBSERVED_AT },
+            price_chg_m5: { value: 4.2, unit: "pct", at: FIXTURE_OBSERVED_AT },
+        },
+        evidence_refs: ["geckoterminal:e2e-test-pool", "hunt:scanner:1"],
+        quality_flags: [],
+        risk_assessment: fixtureRiskAssessment(),
+    };
+}
+export function fixtureRiskAssessment() {
+    return {
+        assessment_id: FIXTURE_ASSESSMENT_ID,
+        opportunity_id: FIXTURE_OPPORTUNITY_ID,
+        decision: "allow",
+        reason_codes: ["S03", "S07"],
+        checked_at: FIXTURE_CHECKED_AT,
+        policy_version: "shield-assess-v1",
+        data_quality: "valid",
+        expires_at: FIXTURE_EXPIRES_AT,
+    };
+}
+export function fixtureEnvelope() {
+    return {
+        schema_version: "0.1",
+        event_id: FIXTURE_EVENT_ID,
+        event_type: EVENT_OPPORTUNITY_DETECTED,
+        occurred_at: FIXTURE_OCCURRED_AT,
+        produced_by: "hunt",
+        correlation_id: FIXTURE_CORRELATION_ID,
+        idempotency_key: `publish:test:${FIXTURE_OPPORTUNITY_ID}`,
+        payload: fixtureOpportunityPayload(),
+    };
+}
+export function fixturePublicationCandidate() {
+    return {
+        publication_id: FIXTURE_PUBLICATION_ID,
+        opportunity_id: FIXTURE_OPPORTUNITY_ID,
+        assessment_id: FIXTURE_ASSESSMENT_ID,
+        channel_id: "test-channel-001",
+        template_id: "signal_card",
+        template_version: "1",
+        content: {
+            text: "[TEST] TEST (solana) — accel 78, liq 25000 USD. " +
+                "assessment asmt-e2e-test-0001 allow/valid until 2099.",
+        },
+        buttons: [{ type: "url", label: "Chart", url: "https://example.com/chart" }],
+        approval_state: "pending_human",
+        expires_at: FIXTURE_EXPIRES_AT,
+        idempotency_key: `publish:test:${FIXTURE_OPPORTUNITY_ID}`,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { valid, invalid, flatMap, isRecord, isString, isNonEmptyString, isStringArray, isTimestamp, isFiniteNumber, isOneOf, cappedId, cappedText, cappedStringList, cappedTimestamp, field, optionalField, MAX_ID_LEN, MAX_TEXT_LEN, MAX_LIST_LEN, } from "./validate.ts";
+export type { Valid, Invalid, ValidationResult } from "./validate.ts";
+export { SCHEMA_VERSION, PRODUCED_BY, EVENT_OPPORTUNITY_DETECTED, validateEnvelope, } from "./envelope.ts";
+export type { EventEnvelope, ProducedBy, EnvelopeOptions } from "./envelope.ts";
+export { validateOpportunityPayload } from "./opportunity.ts";
+export type { OpportunityPayload, OpportunitySource, MarketValue, } from "./opportunity.ts";
+export { RISK_DECISIONS, DATA_QUALITIES, validateRiskAssessment, isAssessmentUsableForPublication, } from "./risk.ts";
+export type { RiskAssessment, RiskDecision, DataQuality, } from "./risk.ts";
+export { validatePublicationCandidate } from "./publication.ts";
+export type { PublicationCandidate, PublicationButton, PublicationContent, } from "./publication.ts";
+export { FIXTURE_EVENT_ID, FIXTURE_CORRELATION_ID, FIXTURE_OPPORTUNITY_ID, FIXTURE_ASSESSMENT_ID, FIXTURE_PUBLICATION_ID, FIXTURE_ASSET_ID, FIXTURE_OCCURRED_AT, FIXTURE_OBSERVED_AT, FIXTURE_CHECKED_AT, FIXTURE_EXPIRES_AT, fixtureEnvelope, fixtureOpportunityPayload, fixtureRiskAssessment, fixturePublicationCandidate, } from "./fixtures.ts";

package/dist/index.js

@@ -0,0 +1,17 @@
+// ============================================================================
+// VIXOR Contracts Package — Public Exports
+// ============================================================================
+// Zero-dependency runtime contracts for the VIXOR integration proof path
+// (mirrors integration/VIXOR_INTEGRATION_CONTRACTS_DRAFT.md §1–§4).
+// --- validation primitives -------------------------------------------------
+export { valid, invalid, flatMap, isRecord, isString, isNonEmptyString, isStringArray, isTimestamp, isFiniteNumber, isOneOf, cappedId, cappedText, cappedStringList, cappedTimestamp, field, optionalField, MAX_ID_LEN, MAX_TEXT_LEN, MAX_LIST_LEN, } from "./validate.js";
+// --- §1 common envelope -----------------------------------------------------
+export { SCHEMA_VERSION, PRODUCED_BY, EVENT_OPPORTUNITY_DETECTED, validateEnvelope, } from "./envelope.js";
+// --- §2 opportunity detected ------------------------------------------------
+export { validateOpportunityPayload } from "./opportunity.js";
+// --- §3 risk assessment ------------------------------------------------------
+export { RISK_DECISIONS, DATA_QUALITIES, validateRiskAssessment, isAssessmentUsableForPublication, } from "./risk.js";
+// --- §4 publication candidate ------------------------------------------------
+export { validatePublicationCandidate } from "./publication.js";
+// --- deterministic fixtures ---------------------------------------------------
+export { FIXTURE_EVENT_ID, FIXTURE_CORRELATION_ID, FIXTURE_OPPORTUNITY_ID, FIXTURE_ASSESSMENT_ID, FIXTURE_PUBLICATION_ID, FIXTURE_ASSET_ID, FIXTURE_OCCURRED_AT, FIXTURE_OBSERVED_AT, FIXTURE_CHECKED_AT, FIXTURE_EXPIRES_AT, fixtureEnvelope, fixtureOpportunityPayload, fixtureRiskAssessment, fixturePublicationCandidate, } from "./fixtures.js";

package/dist/opportunity.d.ts

@@ -0,0 +1,35 @@
+import { type ValidationResult } from "./validate.ts";
+import { type RiskAssessment } from "./risk.ts";
+/** One measured value with its units/currency and observation timestamp (§2 market_data). */
+export interface MarketValue {
+    value: number;
+    unit?: string;
+    currency?: string;
+    at?: string;
+}
+/** §2: "source: source/provider name and source record reference". */
+export interface OpportunitySource {
+    name: string;
+    record_ref: string;
+}
+/**
+ * §2 minimum payload. Field names mirror the draft verbatim.
+ *
+ * `risk_assessment` is a VIXOR extension used on the minimal proof path: the
+ * producer (Hunt emitter) fetches Shield's §3 assessment and embeds it so the
+ * publication ledger can fail closed without an outbound call. Consumers that
+ * require stronger guarantees should verify the assessment against Shield
+ * directly (documented limitation of the proof phase).
+ */
+export interface OpportunityPayload {
+    opportunity_id: string;
+    asset_id: string;
+    symbol: string;
+    source: OpportunitySource;
+    observed_at: string;
+    market_data: Record<string, MarketValue>;
+    evidence_refs: string[];
+    quality_flags: string[];
+    risk_assessment?: RiskAssessment;
+}
+export declare function validateOpportunityPayload(raw: unknown): ValidationResult<OpportunityPayload>;

package/dist/opportunity.js

@@ -0,0 +1,124 @@
+// ============================================================================
+// VIXOR Contracts — §2 Hunt → Core: opportunity detected
+// ============================================================================
+import { cappedId, cappedStringList, cappedTimestamp, field, invalid, isFiniteNumber, isRecord, optionalField, } from "./validate.js";
+import { validateRiskAssessment, } from "./risk.js";
+function validateMarketValue(v, name) {
+    if (!isRecord(v))
+        return invalid(`market_data.${name}: must be an object`);
+    const value = field(v, "value", (x) => isFiniteNumber(x)
+        ? { ok: true, value: x }
+        : { ok: false, errors: [`market_data.${name}.value: must be a finite number`] });
+    if (!value.ok)
+        return value;
+    const unit = optionalField(v, "unit", (x) => typeof x === "string" && x.length <= 50
+        ? { ok: true, value: x }
+        : { ok: false, errors: [`market_data.${name}.unit: must be a string ≤ 50 chars`] });
+    if (!unit.ok)
+        return unit;
+    const currency = optionalField(v, "currency", (x) => typeof x === "string" && x.length <= 10
+        ? { ok: true, value: x }
+        : { ok: false, errors: [`market_data.${name}.currency: must be a string ≤ 10 chars`] });
+    if (!currency.ok)
+        return currency;
+    const at = optionalField(v, "at", (x) => cappedTimestamp(x, `market_data.${name}.at`));
+    if (!at.ok)
+        return at;
+    return {
+        ok: true,
+        value: { value: value.value, unit: unit.value, currency: currency.value, at: at.value },
+    };
+}
+function validateMarketData(v) {
+    if (!isRecord(v))
+        return invalid("market_data: must be an object");
+    const keys = Object.keys(v);
+    if (keys.length === 0)
+        return invalid("market_data: must contain at least one metric");
+    if (keys.length > 50)
+        return invalid("market_data: exceeds 50 metrics");
+    const out = {};
+    for (const k of keys) {
+        if (!/^[a-z0-9_]{1,50}$/.test(k)) {
+            return invalid(`market_data: metric name "${k.slice(0, 50)}" must match [a-z0-9_]{1,50}`);
+        }
+        const mv = validateMarketValue(v[k], k);
+        if (!mv.ok)
+            return mv;
+        out[k] = mv.value;
+    }
+    return { ok: true, value: out };
+}
+export function validateOpportunityPayload(raw) {
+    if (!isRecord(raw))
+        return invalid("payload: must be a JSON object");
+    const opportunityId = field(raw, "opportunity_id", (v) => cappedId(v, "opportunity_id"));
+    if (!opportunityId.ok)
+        return opportunityId;
+    // §2: "asset_id: canonical asset identity, preferably chain/network +
+    // contract or provider ID" — enforce the canonical "chain:address" shape.
+    const assetId = field(raw, "asset_id", (v) => {
+        const id = cappedId(v, "asset_id");
+        if (!id.ok)
+            return id;
+        const colon = id.value.indexOf(":");
+        if (colon <= 0 || colon === id.value.length - 1) {
+            return { ok: false, errors: ["asset_id: must be canonical \"chain:address\""] };
+        }
+        return id;
+    });
+    if (!assetId.ok)
+        return assetId;
+    const symbol = field(raw, "symbol", (v) => {
+        // §2: display only; never sole identity — cap length, allow empty marginally? No: must exist.
+        if (typeof v !== "string" || v.length === 0 || v.length > 50) {
+            return { ok: false, errors: ["symbol: must be a string of 1..50 chars (display only)"] };
+        }
+        return { ok: true, value: v };
+    });
+    if (!symbol.ok)
+        return symbol;
+    const sourceRaw = raw.source;
+    if (!isRecord(sourceRaw))
+        return invalid("source: must be an object");
+    const sourceName = field(sourceRaw, "name", (v) => cappedId(v, "source.name"));
+    if (!sourceName.ok)
+        return sourceName;
+    const sourceRef = field(sourceRaw, "record_ref", (v) => cappedId(v, "source.record_ref"));
+    if (!sourceRef.ok)
+        return sourceRef;
+    const observedAt = field(raw, "observed_at", (v) => cappedTimestamp(v, "observed_at"));
+    if (!observedAt.ok)
+        return observedAt;
+    const marketData = field(raw, "market_data", validateMarketData);
+    if (!marketData.ok)
+        return marketData;
+    const evidenceRefs = field(raw, "evidence_refs", (v) => cappedStringList(v, "evidence_refs"));
+    if (!evidenceRefs.ok)
+        return evidenceRefs;
+    const qualityFlags = field(raw, "quality_flags", (v) => cappedStringList(v, "quality_flags"));
+    if (!qualityFlags.ok)
+        return qualityFlags;
+    // Notes must never smuggle credentials — generic cap, content-agnostic.
+    const riskAssessment = optionalField(raw, "risk_assessment", validateRiskAssessment);
+    if (!riskAssessment.ok)
+        return riskAssessment;
+    if (riskAssessment.value &&
+        riskAssessment.value.opportunity_id !== opportunityId.value) {
+        return invalid("risk_assessment.opportunity_id: must match payload.opportunity_id");
+    }
+    return {
+        ok: true,
+        value: {
+            opportunity_id: opportunityId.value,
+            asset_id: assetId.value,
+            symbol: symbol.value,
+            source: { name: sourceName.value, record_ref: sourceRef.value },
+            observed_at: observedAt.value,
+            market_data: marketData.value,
+            evidence_refs: evidenceRefs.value,
+            quality_flags: qualityFlags.value,
+            risk_assessment: riskAssessment.value,
+        },
+    };
+}

package/dist/publication.d.ts

@@ -0,0 +1,30 @@
+import { type ValidationResult } from "./validate.ts";
+/** §4: "buttons: allow-listed action types and validated destinations". */
+export interface PublicationButton {
+    type: string;
+    label: string;
+    url: string;
+}
+/** §4: "content: rendered text/media references". */
+export interface PublicationContent {
+    text: string;
+    media_refs?: string[];
+}
+/**
+ * §4 minimum payload, mirrored field-for-field. `approval_state` starts at
+ * `pending_human` — a candidate can never enter the ledger pre-approved.
+ */
+export interface PublicationCandidate {
+    publication_id: string;
+    opportunity_id: string;
+    assessment_id: string;
+    channel_id: string;
+    template_id: string;
+    template_version: string;
+    content: PublicationContent;
+    buttons?: PublicationButton[];
+    approval_state: "pending_human";
+    expires_at: string;
+    idempotency_key: string;
+}
+export declare function validatePublicationCandidate(raw: unknown): ValidationResult<PublicationCandidate>;

package/dist/publication.js

@@ -0,0 +1,124 @@
+// ============================================================================
+// VIXOR Contracts — §4 Core → tg-content-bot: publication candidate
+// ============================================================================
+import { cappedId, cappedText, cappedTimestamp, field, invalid, isRecord, optionalField, } from "./validate.js";
+import { validateRiskAssessment } from "./risk.js";
+const BUTTON_TYPES = ["url"];
+function validateButton(v, idx) {
+    if (!isRecord(v))
+        return invalid(`buttons[${idx}]: must be an object`);
+    const type = field(v, "type", (x) => typeof x === "string" && BUTTON_TYPES.includes(x)
+        ? { ok: true, value: x }
+        : { ok: false, errors: [`buttons[${idx}].type: not an allow-listed action type`] });
+    if (!type.ok)
+        return type;
+    const label = field(v, "label", (x) => cappedText(x, `buttons[${idx}].label`));
+    if (!label.ok)
+        return label;
+    const url = field(v, "url", (x) => {
+        if (typeof x !== "string" || x.length > 500) {
+            return { ok: false, errors: [`buttons[${idx}].url: must be a string of at most 500 chars`] };
+        }
+        let parsed;
+        try {
+            parsed = new URL(x);
+        }
+        catch {
+            return { ok: false, errors: [`buttons[${idx}].url: must be a valid absolute https URL`] };
+        }
+        if (parsed.protocol !== "https:" || !parsed.hostname || parsed.username || parsed.password) {
+            return { ok: false, errors: [`buttons[${idx}].url: must be https and cannot contain credentials`] };
+        }
+        return { ok: true, value: parsed.toString() };
+    });
+    if (!url.ok)
+        return url;
+    return { ok: true, value: { type: type.value, label: label.value, url: url.value } };
+}
+export function validatePublicationCandidate(raw) {
+    if (!isRecord(raw))
+        return invalid("publication_candidate: must be a JSON object");
+    const publicationId = field(raw, "publication_id", (v) => cappedId(v, "publication_id"));
+    if (!publicationId.ok)
+        return publicationId;
+    const opportunityId = field(raw, "opportunity_id", (v) => cappedId(v, "opportunity_id"));
+    if (!opportunityId.ok)
+        return opportunityId;
+    const assessmentId = field(raw, "assessment_id", (v) => cappedId(v, "assessment_id"));
+    if (!assessmentId.ok)
+        return assessmentId;
+    // §4: "channel_id: approved internal identifier, not an arbitrary
+    // destination supplied by an event" — shape-level check only; the ledger
+    // must additionally verify it exists internally before use.
+    const channelId = field(raw, "channel_id", (v) => cappedId(v, "channel_id"));
+    if (!channelId.ok)
+        return channelId;
+    const templateId = field(raw, "template_id", (v) => cappedId(v, "template_id"));
+    if (!templateId.ok)
+        return templateId;
+    const templateVersion = field(raw, "template_version", (v) => cappedId(v, "template_version"));
+    if (!templateVersion.ok)
+        return templateVersion;
+    const contentRaw = raw.content;
+    if (!isRecord(contentRaw))
+        return invalid("content: must be an object");
+    const text = field(contentRaw, "text", (v) => cappedText(v, "content.text"));
+    if (!text.ok)
+        return text;
+    const mediaRefs = optionalField(contentRaw, "media_refs", (v) => {
+        if (!Array.isArray(v) || v.length > 10 || !v.every((x) => typeof x === "string")) {
+            return { ok: false, errors: ["content.media_refs: must be ≤ 10 strings"] };
+        }
+        return { ok: true, value: v };
+    });
+    if (!mediaRefs.ok)
+        return mediaRefs;
+    const buttons = optionalField(raw, "buttons", (v) => {
+        if (!Array.isArray(v))
+            return { ok: false, errors: ["buttons: must be an array"] };
+        if (v.length > 8)
+            return { ok: false, errors: ["buttons: exceeds 8 buttons"] };
+        const out = [];
+        for (let i = 0; i < v.length; i++) {
+            const b = validateButton(v[i], i);
+            if (!b.ok)
+                return b;
+            out.push(b.value);
+        }
+        return { ok: true, value: out };
+    });
+    if (!buttons.ok)
+        return buttons;
+    // §4: "approval_state: initially pending_human" — literally enforced.
+    const approvalState = field(raw, "approval_state", (v) => v === "pending_human"
+        ? { ok: true, value: "pending_human" }
+        : { ok: false, errors: ["approval_state: must be exactly \"pending_human\""] });
+    if (!approvalState.ok)
+        return approvalState;
+    const expiresAt = field(raw, "expires_at", (v) => cappedTimestamp(v, "expires_at"));
+    if (!expiresAt.ok)
+        return expiresAt;
+    const idempotencyKey = field(raw, "idempotency_key", (v) => cappedId(v, "idempotency_key"));
+    if (!idempotencyKey.ok)
+        return idempotencyKey;
+    // risk_assessment presence is not part of §4; validate if supplied (helper reuse).
+    const extraAssessment = optionalField(raw, "risk_assessment", validateRiskAssessment);
+    if (!extraAssessment.ok)
+        return extraAssessment;
+    return {
+        ok: true,
+        value: {
+            publication_id: publicationId.value,
+            opportunity_id: opportunityId.value,
+            assessment_id: assessmentId.value,
+            channel_id: channelId.value,
+            template_id: templateId.value,
+            template_version: templateVersion.value,
+            content: { text: text.value, media_refs: mediaRefs.value },
+            buttons: buttons.value,
+            approval_state: "pending_human",
+            expires_at: expiresAt.value,
+            idempotency_key: idempotencyKey.value,
+        },
+    };
+}

package/dist/risk.d.ts

@@ -0,0 +1,30 @@
+import { type ValidationResult } from "./validate.ts";
+export declare const RISK_DECISIONS: readonly ["allow", "reject", "review"];
+export type RiskDecision = (typeof RISK_DECISIONS)[number];
+export declare const DATA_QUALITIES: readonly ["valid", "stale", "incomplete", "conflicting"];
+export type DataQuality = (typeof DATA_QUALITIES)[number];
+/**
+ * Shield's /assess response (§3): "Shield response must include" — mirrored
+ * field-for-field. Any decision other than a verbatim match is rejected.
+ */
+export interface RiskAssessment {
+    assessment_id: string;
+    opportunity_id: string;
+    decision: RiskDecision;
+    reason_codes: string[];
+    checked_at: string;
+    policy_version: string;
+    data_quality: DataQuality;
+    expires_at: string;
+}
+export declare function validateRiskAssessment(raw: unknown): ValidationResult<RiskAssessment>;
+/**
+ * §3 gate: "A missing response, unknown decision, expired assessment, or
+ * non-valid data quality must block publication."
+ *
+ * Publication is allowed only when the decision is `allow`, the data quality
+ * is exactly `valid`, and the assessment has not expired. Anything else
+ * blocks — including `review` (human triage may override later by explicit
+ * owner action, never by default).
+ */
+export declare function isAssessmentUsableForPublication(a: RiskAssessment, nowMs: number): boolean;

package/dist/risk.js

@@ -0,0 +1,73 @@
+// ============================================================================
+// VIXOR Contracts — §3 Shield risk assessment (DRAFT §3 response shape)
+// ============================================================================
+import { cappedId, cappedStringList, cappedTimestamp, field, invalid, isOneOf, isRecord, } from "./validate.js";
+export const RISK_DECISIONS = ["allow", "reject", "review"];
+export const DATA_QUALITIES = [
+    "valid",
+    "stale",
+    "incomplete",
+    "conflicting",
+];
+export function validateRiskAssessment(raw) {
+    if (!isRecord(raw))
+        return invalid("risk_assessment: must be a JSON object");
+    const assessmentId = field(raw, "assessment_id", (v) => cappedId(v, "assessment_id"));
+    if (!assessmentId.ok)
+        return assessmentId;
+    const opportunityId = field(raw, "opportunity_id", (v) => cappedId(v, "opportunity_id"));
+    if (!opportunityId.ok)
+        return opportunityId;
+    const decision = field(raw, "decision", (v) => isOneOf(v, RISK_DECISIONS)
+        ? { ok: true, value: v }
+        : { ok: false, errors: ["decision: must be one of allow|reject|review"] });
+    if (!decision.ok)
+        return decision;
+    const reasonCodes = field(raw, "reason_codes", (v) => cappedStringList(v, "reason_codes"));
+    if (!reasonCodes.ok)
+        return reasonCodes;
+    const checkedAt = field(raw, "checked_at", (v) => cappedTimestamp(v, "checked_at"));
+    if (!checkedAt.ok)
+        return checkedAt;
+    const policyVersion = field(raw, "policy_version", (v) => cappedId(v, "policy_version"));
+    if (!policyVersion.ok)
+        return policyVersion;
+    const dataQuality = field(raw, "data_quality", (v) => isOneOf(v, DATA_QUALITIES)
+        ? { ok: true, value: v }
+        : { ok: false, errors: ["data_quality: must be one of valid|stale|incomplete|conflicting"] });
+    if (!dataQuality.ok)
+        return dataQuality;
+    const expiresAt = field(raw, "expires_at", (v) => cappedTimestamp(v, "expires_at"));
+    if (!expiresAt.ok)
+        return expiresAt;
+    return {
+        ok: true,
+        value: {
+            assessment_id: assessmentId.value,
+            opportunity_id: opportunityId.value,
+            decision: decision.value,
+            reason_codes: reasonCodes.value,
+            checked_at: checkedAt.value,
+            policy_version: policyVersion.value,
+            data_quality: dataQuality.value,
+            expires_at: expiresAt.value,
+        },
+    };
+}
+/**
+ * §3 gate: "A missing response, unknown decision, expired assessment, or
+ * non-valid data quality must block publication."
+ *
+ * Publication is allowed only when the decision is `allow`, the data quality
+ * is exactly `valid`, and the assessment has not expired. Anything else
+ * blocks — including `review` (human triage may override later by explicit
+ * owner action, never by default).
+ */
+export function isAssessmentUsableForPublication(a, nowMs) {
+    if (a.decision !== "allow")
+        return false;
+    if (a.data_quality !== "valid")
+        return false;
+    const exp = Date.parse(a.expires_at);
+    return Number.isFinite(exp) && exp > nowMs;
+}

package/dist/validate.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Hand-rolled validation helpers (house style: the sibling engines validate
+ * by hand, no zod at runtime). Everything here is pure and deterministic.
+ *
+ * Result shape: `{ ok: true, value }` or `{ ok: false, errors: string[] }`.
+ * Errors are safe, redacted messages — never echo payload secrets.
+ */
+export type Valid<T> = {
+    ok: true;
+    value: T;
+};
+export type Invalid = {
+    ok: false;
+    errors: string[];
+};
+export type ValidationResult<T> = Valid<T> | Invalid;
+export declare function valid<T>(value: T): Valid<T>;
+export declare function invalid(...errors: string[]): Invalid;
+/** Merge two results; short-circuits on the first invalid one. */
+export declare function flatMap<T, U>(r: ValidationResult<T>, f: (value: T) => ValidationResult<U>): ValidationResult<U>;
+export declare function isRecord(v: unknown): v is Record<string, unknown>;
+export declare function isString(v: unknown): v is string;
+export declare function isNonEmptyString(v: unknown): v is string;
+export declare function isStringArray(v: unknown): v is string[];
+/** Any string that `Date.parse` accepts (ISO-8601 UTC expected in practice). */
+export declare function isTimestamp(v: unknown): v is string;
+export declare function isFiniteNumber(v: unknown): v is number;
+export declare function isOneOf<T extends string>(v: unknown, allowed: readonly T[]): v is T;
+/** Hard length caps — hygiene against oversized/abusive fields. */
+export declare const MAX_ID_LEN = 200;
+export declare const MAX_TEXT_LEN = 8000;
+export declare const MAX_LIST_LEN = 50;
+export declare function cappedId(v: unknown, field: string): ValidationResult<string>;
+export declare function cappedText(v: unknown, field: string): ValidationResult<string>;
+export declare function cappedStringList(v: unknown, field: string): ValidationResult<string[]>;
+export declare function cappedTimestamp(v: unknown, field: string): ValidationResult<string>;
+/** Read a required field from a record and validate it. */
+export declare function field<T>(rec: Record<string, unknown>, name: string, validate: (v: unknown) => ValidationResult<T>): ValidationResult<T>;
+/** Read an optional field; absent → undefined, present-but-invalid → error. */
+export declare function optionalField<T>(rec: Record<string, unknown>, name: string, validate: (v: unknown) => ValidationResult<T>): ValidationResult<T | undefined>;

package/dist/validate.js

@@ -0,0 +1,80 @@
+// ============================================================================
+// VIXOR Contracts — minimal zero-dependency runtime validators
+// ============================================================================
+export function valid(value) {
+    return { ok: true, value };
+}
+export function invalid(...errors) {
+    return { ok: false, errors };
+}
+/** Merge two results; short-circuits on the first invalid one. */
+export function flatMap(r, f) {
+    return r.ok ? f(r.value) : r;
+}
+export function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+export function isString(v) {
+    return typeof v === "string";
+}
+export function isNonEmptyString(v) {
+    return typeof v === "string" && v.length > 0;
+}
+export function isStringArray(v) {
+    return Array.isArray(v) && v.every((x) => typeof x === "string");
+}
+/** Any string that `Date.parse` accepts (ISO-8601 UTC expected in practice). */
+export function isTimestamp(v) {
+    if (typeof v !== "string")
+        return false;
+    const t = Date.parse(v);
+    return Number.isFinite(t);
+}
+export function isFiniteNumber(v) {
+    return typeof v === "number" && Number.isFinite(v);
+}
+export function isOneOf(v, allowed) {
+    return typeof v === "string" && allowed.includes(v);
+}
+/** Hard length caps — hygiene against oversized/abusive fields. */
+export const MAX_ID_LEN = 200;
+export const MAX_TEXT_LEN = 8000;
+export const MAX_LIST_LEN = 50;
+export function cappedId(v, field) {
+    if (!isNonEmptyString(v))
+        return invalid(`${field}: must be a non-empty string`);
+    if (v.length > MAX_ID_LEN)
+        return invalid(`${field}: exceeds ${MAX_ID_LEN} chars`);
+    return valid(v);
+}
+export function cappedText(v, field) {
+    if (!isString(v))
+        return invalid(`${field}: must be a string`);
+    if (v.length > MAX_TEXT_LEN)
+        return invalid(`${field}: exceeds ${MAX_TEXT_LEN} chars`);
+    return valid(v);
+}
+export function cappedStringList(v, field) {
+    if (!isStringArray(v))
+        return invalid(`${field}: must be an array of strings`);
+    if (v.length > MAX_LIST_LEN)
+        return invalid(`${field}: exceeds ${MAX_LIST_LEN} items`);
+    return valid(v);
+}
+export function cappedTimestamp(v, field) {
+    if (!isTimestamp(v))
+        return invalid(`${field}: must be a parseable timestamp`);
+    return valid(v);
+}
+/** Read a required field from a record and validate it. */
+export function field(rec, name, validate) {
+    if (!(name in rec))
+        return invalid(`${name}: missing required field`);
+    return validate(rec[name]);
+}
+/** Read an optional field; absent → undefined, present-but-invalid → error. */
+export function optionalField(rec, name, validate) {
+    if (!(name in rec) || rec[name] === undefined)
+        return valid(undefined);
+    return validate(rec[name]);
+}

package/package.json

@@ -1,42 +1,42 @@
-{
-  "name": "@vixor/contracts",
-  "version": "0.2.0",
-  "description": "Zero-dependency runtime contracts and validators for VIXOR crypto-intelligence integrations.",
-  "license": "UNLICENSED",
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "default": "./dist/index.js"
-    }
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "sideEffects": false,
-  "engines": {
-    "node": ">=20"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "typecheck": "tsc --noEmit",
-    "test": "node --experimental-strip-types --test test/contracts.test.ts",
-    "pack:check": "node scripts/verify-pack.mjs"
-  },
-  "devDependencies": {
-    "@types/node": "^22.16.5",
-    "typescript": "^5.8.3"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/kam65624-cmd/vixor-packages.git",
-    "directory": "packages/vixor-contracts"
-  }
-}
+{
+  "name": "@vixor/contracts",
+  "version": "0.2.1",
+  "description": "Zero-dependency runtime contracts and validators for VIXOR crypto-intelligence integrations.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "node --experimental-strip-types --test test/contracts.test.ts",
+    "pack:check": "node scripts/verify-pack.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "^22.16.5",
+    "typescript": "^5.8.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kam65624-cmd/vixor-packages.git",
+    "directory": "packages/vixor-contracts"
+  }
+}