@motebit/protocol 1.0.0 → 1.2.0

package/dist/skills.d.ts

@@ -0,0 +1,334 @@
+/**
+ * Skill manifest + envelope types — motebit/skills@1.0.
+ *
+ * Permissive floor (Apache-2.0): these types define the interoperable wire
+ * format for a motebit skill — agentskills.io-compatible frontmatter with
+ * motebit-namespaced extensions for cryptographic provenance, sensitivity-
+ * tiered loading, and hardware-attestation gating. See spec/skills-v1.md.
+ *
+ * The parsed frontmatter object (`SkillManifest`) is the wire artifact; the
+ * YAML in `SKILL.md` is the on-disk encoding only. JSON-over-wire and the
+ * `skill-envelope.json` wrapper both serialize to the types declared here.
+ *
+ * Audience-distinct from credentials (peer-issued reputation/trust attestations,
+ * spec/credential-v1.md) and execution receipts (per-invocation audit,
+ * spec/execution-ledger-v1.md). Phase 3 of skills-v1 will emit
+ * `SkillLoadReceipt` entries into the execution ledger; that schema lives in
+ * the ledger module, not here.
+ *
+ * Layer purity (per packages/protocol/CLAUDE.md): types only. Canonicalization
+ * and signature verification live in @motebit/crypto. Frontmatter parsing,
+ * registry, selector, and trust gate live in the BSL @motebit/skills package.
+ */
+import type { SuiteId } from "./crypto-suite.js";
+/**
+ * Sensitivity tier of the data a skill's procedure causes the agent to touch.
+ *
+ * Sensitivity describes data, not provenance — see spec/skills-v1.md §4.
+ * `medical`, `financial`, and `secret` skills are NEVER auto-loaded by the
+ * `SkillSelector` regardless of session tier; they require explicit per-turn
+ * opt-in or operator-mode session promotion.
+ */
+export type SkillSensitivity = "none" | "personal" | "medical" | "financial" | "secret";
+/** Frozen list of sensitivity tiers in increasing-restriction order. */
+export declare const SKILL_SENSITIVITY_TIERS: readonly SkillSensitivity[];
+/** Tiers that are auto-loadable when session tier permits. */
+export declare const SKILL_AUTO_LOADABLE_TIERS: readonly SkillSensitivity[];
+/** OS gate per agentskills.io `platforms` field. Empty/omitted = all platforms. */
+export type SkillPlatform = "macos" | "linux" | "windows" | "ios" | "android";
+/** Frozen list of recognized platform identifiers. */
+export declare const SKILL_PLATFORMS: readonly SkillPlatform[];
+/**
+ * Hardware-attestation gate for skill loading.
+ *
+ * Additive scoring per docs/doctrine/hardware-attestation.md — never a hard
+ * wall on the agent's own identity, but a skill MAY require its loading
+ * runtime to present a minimum HA score. Sibling pattern to the
+ * HardwareAttestationSemiring used in routing.
+ */
+export interface SkillHardwareAttestationGate {
+    /** If `true`, loading agent must present an HA credential. Default `false`. */
+    required?: boolean;
+    /** Minimum score in `[0, 1]` required for load. Default `0`. */
+    minimum_score?: number;
+}
+/**
+ * Cryptographic provenance for a skill — sibling shape to other motebit
+ * signed artifacts (settlement anchor, migration, execution receipts, etc.).
+ *
+ * The signature value is over the canonical form defined in
+ * spec/skills-v1.md §5.1: `JCS(manifest_without_value) || 0x0A || lf_body`.
+ * v1 uses `motebit-jcs-ed25519-b64-v1` — same suite as execution receipts and
+ * other motebit-internal signed artifacts. Skills are NOT W3C `eddsa-jcs-2022`
+ * DataIntegrityProof artifacts; that suite is reserved for credentials,
+ * identity files, and presentations that need third-party W3C interop. Skills
+ * install and verify locally on motebit runtimes, so they use the simpler
+ * concat-bytes recipe consistent with the rest of the internal artifact
+ * surface. Future suites (incl. PQ) are registry additions per
+ * `architecture_cryptosuite_agility`.
+ */
+export interface SkillSignature {
+    /** Cryptosuite discriminator. Verifiers reject unknown values fail-closed. */
+    suite: SuiteId;
+    /** Hex-encoded Ed25519 public key (32 bytes → 64 lowercase hex chars). */
+    public_key: string;
+    /** Base64url-encoded Ed25519 signature over the canonical bytes. */
+    value: string;
+}
+/**
+ * Free-form display metadata per agentskills.io.
+ *
+ * `author` is a presentation field — NOT cryptographically verified. The
+ * cryptographic author lives at `motebit.signature.public_key`. SDKs SHOULD
+ * lint-warn (not reject) when a `did:key`-shaped value here disagrees with
+ * the signature key. See spec/skills-v1.md §3.1.
+ */
+export interface SkillManifestMetadata {
+    /** Free-form display string. Examples: `"Jane Doe"`, `"@janedoe"`, `"did:key:z6Mk..."`. */
+    author?: string;
+    /** Free-form category for UI grouping. Never load-bearing. */
+    category?: string;
+    /** Free-form tags for UI filtering. */
+    tags?: string[];
+    /**
+     * Per-skill configuration values. Keys and shapes are skill-defined; the
+     * runtime injects them via `skills.config.<key>` per agentskills.io
+     * conventions.
+     */
+    config?: Record<string, unknown>;
+}
+/**
+ * The motebit-namespaced extension block.
+ *
+ * Non-motebit agentskills.io runtimes ignore this entire object. Only
+ * `spec_version` is required — the rest defaults per spec/skills-v1.md §3.1
+ * (sensitivity → `"none"`, hardware_attestation → `{ required: false,
+ * minimum_score: 0 }`, signature absent → unsigned skill).
+ */
+export interface SkillManifestMotebit {
+    /** Spec version. v1: `"1.0"`. Gates compatibility for future bumps. */
+    spec_version: "1.0";
+    /** Sensitivity tier. Defaults to `"none"` if undeclared. */
+    sensitivity?: SkillSensitivity;
+    /** Hardware-attestation gate. Defaults to `{ required: false, minimum_score: 0 }`. */
+    hardware_attestation?: SkillHardwareAttestationGate;
+    /** Cryptographic signature. Absent = unsigned skill (NEVER auto-loaded by selector). */
+    signature?: SkillSignature;
+}
+/**
+ * The full parsed SKILL.md frontmatter.
+ *
+ * Wire format for skills exchanged over network or registry boundaries.
+ * Defaults for optional fields are applied by the parser (BSL
+ * @motebit/skills); the protocol type matches the literal JSON shape with
+ * optionals where the spec marks them optional.
+ */
+export interface SkillManifest {
+    /** Globally unique slug within an installation: `[a-z0-9-]+`. */
+    name: string;
+    /** One-line description. Read by the loader to decide skill relevance. */
+    description: string;
+    /** SemVer string. */
+    version: string;
+    /** OS gate. Empty/omitted = all platforms. */
+    platforms?: SkillPlatform[];
+    /** Free-form display metadata. */
+    metadata?: SkillManifestMetadata;
+    /** Motebit extension block. `spec_version` required; all other fields default. */
+    motebit: SkillManifestMotebit;
+}
+/**
+ * One file in the skill envelope's `files` list.
+ *
+ * Each entry pins a relative path to its hex-encoded SHA-256 hash. Install
+ * verifies envelope signature first, then re-derives every file hash from the
+ * unpacked tree and asserts equality. Any mismatch aborts install with no
+ * partial state (spec/skills-v1.md §6).
+ */
+export interface SkillEnvelopeFile {
+    /** Path relative to the skill directory (e.g., `"scripts/run.sh"`). */
+    path: string;
+    /** Hex-encoded SHA-256 hash of the file bytes (lowercase, no `0x` prefix). */
+    hash: string;
+}
+/**
+ * Compact identity reference embedded in the envelope for indexing.
+ */
+export interface SkillEnvelopeSkillRef {
+    /** Skill name (matches `SkillManifest.name`). */
+    name: string;
+    /** Skill version (matches `SkillManifest.version`). */
+    version: string;
+    /**
+     * Hex-encoded SHA-256 over `JCS(manifest) || 0x0A || lf_body`. Sibling to
+     * the `body_hash` field but covers the manifest as well — installers use
+     * this as the content-addressed identifier for the skill version.
+     */
+    content_hash: string;
+}
+/**
+ * Content-addressed signed wrapper for skill distribution and install.
+ *
+ * The envelope's `signature.value` is computed over JCS-canonicalized
+ * envelope bytes with `signature.value` removed (sibling to the manifest
+ * scheme in §5.1). Installers verify the envelope signature, then re-derive
+ * `body_hash` and every `files[].hash` from the unpacked tree.
+ */
+export interface SkillEnvelope {
+    /** Spec version. v1: `"1.0"`. */
+    spec_version: "1.0";
+    /** Compact skill reference for indexing. */
+    skill: SkillEnvelopeSkillRef;
+    /** Full parsed manifest (the same object that is the source of truth in SKILL.md). */
+    manifest: SkillManifest;
+    /** Hex-encoded SHA-256 of the LF-normalized body bytes. */
+    body_hash: string;
+    /** Pinned hashes of every file in the skill directory beyond SKILL.md and skill-envelope.json. */
+    files: SkillEnvelopeFile[];
+    /** Envelope signature — same suite as the manifest signature. */
+    signature: SkillSignature;
+}
+/**
+ * Per-skill audit payload emitted by the runtime when the `SkillSelector`
+ * pulls a skill body into the agent's system context. One event per
+ * selected skill per turn, written to the agent's execution ledger as
+ * `EventType.SkillLoaded` (spec/skills-v1.md §7.4).
+ *
+ * The audit trail lets a user prove later: "the obsidian skill ran on
+ * date X with this exact signature value at session sensitivity Y." The
+ * `skill_signature` field is the envelope's `signature.value` — a
+ * content-addressed pointer to the exact bytes injected, recoverable by
+ * looking up the installed skill at `~/.motebit/skills/<name>/`.
+ *
+ * Wire-level event-envelope (timestamp, event_id, motebit_id) lives at
+ * `EventLogEntry`; the per-skill detail is here.
+ */
+export interface SkillLoadPayload {
+    /** Composite identifier `"name@version"` — convenient for log queries. */
+    skill_id: string;
+    /** Skill slug (matches `SkillManifest.name`). */
+    skill_name: string;
+    /** Skill SemVer (matches `SkillManifest.version`). */
+    skill_version: string;
+    /**
+     * Base64url-encoded envelope signature value. Pins the audit entry to
+     * the exact bytes that were on disk at load time — re-signing the skill
+     * (e.g., via `pnpm --filter @motebit/skills build-reference-skill`)
+     * produces a different value, so a stale ledger entry whose signature
+     * doesn't resolve in the current registry is itself a useful audit
+     * signal. Empty string when the manifest is `trusted_unsigned` (operator-
+     * attested but no cryptographic signature exists to record).
+     */
+    skill_signature: string;
+    /** Provenance status at load time. Display-grade copy of `SkillProvenanceStatus`. */
+    provenance: "verified" | "trusted_unsigned";
+    /** BM25 relevance score against the user's turn. Higher = more relevant. */
+    score: number;
+    /**
+     * Run identifier the load is keyed to. Matches the `runId` passed to
+     * `runtime.sendMessage` / `sendMessageStreaming` — pairs every skill
+     * load with the turn that triggered it. Optional because the runtime
+     * may emit loads outside an explicit run context (e.g., proactive
+     * cycles, future).
+     */
+    run_id?: string;
+    /** Session sensitivity tier in effect when the skill loaded. */
+    session_sensitivity: SkillSensitivity;
+}
+/**
+ * One row in the relay-hosted skills registry. Returned in `discover`
+ * listings; one entry per submitted skill version.
+ *
+ * The display fields (`description`, `sensitivity`, `platforms`,
+ * `category`, `tags`, `author`) are denormalized from the embedded
+ * manifest so the discover query does not need to round-trip the full
+ * bundle for each row.
+ *
+ * `submitter_motebit_id` is canonical: derived from `envelope.signature.public_key`
+ * by the relay, never user-provided. Submitter spoofing is impossible.
+ */
+export interface SkillRegistryEntry {
+    /** `did:key` derived from `envelope.signature.public_key`. */
+    submitter_motebit_id: string;
+    /** Slug. Matches `manifest.name`. */
+    name: string;
+    /** SemVer. Matches `manifest.version`. */
+    version: string;
+    /** 64 hex chars; SHA-256 over `JCS(manifest) || 0x0A || lf_body`. */
+    content_hash: string;
+    description: string;
+    sensitivity: SkillSensitivity;
+    platforms?: SkillPlatform[];
+    category?: string;
+    tags?: string[];
+    author?: string;
+    /** 64 hex chars; mirrors `envelope.signature.public_key`. */
+    signature_public_key: string;
+    /** True iff the submitter is in the relay's featured-submitters allowlist. */
+    featured: boolean;
+    /** Unix ms. */
+    submitted_at: number;
+}
+/**
+ * Body of `POST /api/v1/skills/submit`. Carries the full signed
+ * envelope plus body and aux files as base64 strings. The relay
+ * re-derives `body_hash` and per-file hashes and asserts they match
+ * the envelope before persisting.
+ *
+ * The submitter is NOT named in this payload — the relay computes it
+ * canonically from `envelope.signature.public_key`.
+ */
+export interface SkillRegistrySubmitRequest {
+    envelope: SkillEnvelope;
+    /** Base64-encoded LF-normalized SKILL.md body bytes. */
+    body: string;
+    /** Base64-encoded auxiliary file bytes. Keys are the same paths as `envelope.files[].path`. */
+    files?: Record<string, string>;
+}
+/**
+ * Response body of `POST /api/v1/skills/submit` on success. Returns
+ * the canonical addressing tuple plus the relay-computed
+ * `submitter_motebit_id` so the caller can confirm the relay derived
+ * the same `did:key` it expected.
+ */
+export interface SkillRegistrySubmitResponse {
+    /** `<submitter_motebit_id>/<name>@<version>`. */
+    skill_id: string;
+    submitter_motebit_id: string;
+    name: string;
+    version: string;
+    content_hash: string;
+    submitted_at: number;
+}
+/**
+ * Response body of `GET /api/v1/skills/discover`. A paginated page of
+ * `SkillRegistryEntry` rows plus pagination metadata.
+ */
+export interface SkillRegistryListing {
+    entries: SkillRegistryEntry[];
+    /** Total rows matching the filter — not just this page. */
+    total: number;
+    /** Page size used (default 50, max 200). */
+    limit: number;
+    /** Page offset used (default 0). */
+    offset: number;
+}
+/**
+ * Response body of `GET /api/v1/skills/:submitter/:name/:version`.
+ * Carries the full signed envelope, body, and any auxiliary files as
+ * base64 strings. Same shape as `SkillRegistrySubmitRequest` plus a
+ * `submitter_motebit_id` echo so consumers can confirm the resolved
+ * address before re-verifying.
+ */
+export interface SkillRegistryBundle {
+    /** Echoed from the route param; equals `publicKeyToDidKey(envelope.signature.public_key)`. */
+    submitter_motebit_id: string;
+    envelope: SkillEnvelope;
+    /** Base64-encoded LF-normalized SKILL.md body bytes. */
+    body: string;
+    /** Base64-encoded auxiliary file bytes. */
+    files?: Record<string, string>;
+    submitted_at: number;
+    featured: boolean;
+}
+//# sourceMappingURL=skills.d.ts.map

package/dist/skills.d.ts.map

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

package/dist/skills.js

@@ -0,0 +1,44 @@
+/**
+ * Skill manifest + envelope types — motebit/skills@1.0.
+ *
+ * Permissive floor (Apache-2.0): these types define the interoperable wire
+ * format for a motebit skill — agentskills.io-compatible frontmatter with
+ * motebit-namespaced extensions for cryptographic provenance, sensitivity-
+ * tiered loading, and hardware-attestation gating. See spec/skills-v1.md.
+ *
+ * The parsed frontmatter object (`SkillManifest`) is the wire artifact; the
+ * YAML in `SKILL.md` is the on-disk encoding only. JSON-over-wire and the
+ * `skill-envelope.json` wrapper both serialize to the types declared here.
+ *
+ * Audience-distinct from credentials (peer-issued reputation/trust attestations,
+ * spec/credential-v1.md) and execution receipts (per-invocation audit,
+ * spec/execution-ledger-v1.md). Phase 3 of skills-v1 will emit
+ * `SkillLoadReceipt` entries into the execution ledger; that schema lives in
+ * the ledger module, not here.
+ *
+ * Layer purity (per packages/protocol/CLAUDE.md): types only. Canonicalization
+ * and signature verification live in @motebit/crypto. Frontmatter parsing,
+ * registry, selector, and trust gate live in the BSL @motebit/skills package.
+ */
+/** Frozen list of sensitivity tiers in increasing-restriction order. */
+export const SKILL_SENSITIVITY_TIERS = Object.freeze([
+    "none",
+    "personal",
+    "medical",
+    "financial",
+    "secret",
+]);
+/** Tiers that are auto-loadable when session tier permits. */
+export const SKILL_AUTO_LOADABLE_TIERS = Object.freeze([
+    "none",
+    "personal",
+]);
+/** Frozen list of recognized platform identifiers. */
+export const SKILL_PLATFORMS = Object.freeze([
+    "macos",
+    "linux",
+    "windows",
+    "ios",
+    "android",
+]);
+//# sourceMappingURL=skills.js.map

package/dist/skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.js","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAgBH,wEAAwE;AACxE,MAAM,CAAC,MAAM,uBAAuB,GAAgC,MAAM,CAAC,MAAM,CAAC;IAChF,MAAM;IACN,UAAU;IACV,SAAS;IACT,WAAW;IACX,QAAQ;CACT,CAAC,CAAC;AAEH,8DAA8D;AAC9D,MAAM,CAAC,MAAM,yBAAyB,GAAgC,MAAM,CAAC,MAAM,CAAC;IAClF,MAAM;IACN,UAAU;CACX,CAAC,CAAC;AAOH,sDAAsD;AACtD,MAAM,CAAC,MAAM,eAAe,GAA6B,MAAM,CAAC,MAAM,CAAC;IACrE,OAAO;IACP,OAAO;IACP,SAAS;IACT,KAAK;IACL,SAAS;CACV,CAAC,CAAC"}

package/dist/trust-algebra.d.ts

@@ -30,5 +30,20 @@ export declare function trustMultiply(a: number, b: number): number;
 export declare function composeTrustChain(scores: number[]): number;
 /** Fold parallel route scores with ⊕. No routes → 0.0 (identity). */
 export declare function joinParallelRoutes(scores: number[]): number;
+export declare const REFERENCE_TRUST_THRESHOLDS: TrustTransitionThresholds;
+/**
+ * @deprecated since 1.0.1, removed in 2.0.0. Use {@link REFERENCE_TRUST_THRESHOLDS} instead.
+ *
+ * Reason: the `DEFAULT_` prefix read as "THE value every motebit
+ * implementation uses," but trust-transition thresholds are motebit
+ * product tuning — they govern promotion and demotion policy, not
+ * protocol interop. A third-party motebit implementation may choose
+ * different thresholds and still interoperate correctly (the semiring
+ * algebra above is the interop contract). The `REFERENCE_` prefix
+ * signals "motebit's reference-implementation default; implementers
+ * MAY choose their own values." Rename-plus-deprecate so the naming
+ * correction ships without a breaking change; the old export is
+ * removed at 2.0.0.
+ */
 export declare const DEFAULT_TRUST_THRESHOLDS: TrustTransitionThresholds;
 //# sourceMappingURL=trust-algebra.d.ts.map

package/dist/trust-algebra.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trust-algebra.d.ts","sourceRoot":"","sources":["../src/trust-algebra.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,yBAAyB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAI7E;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAMrD,CAAC;AAEF,kDAAkD;AAClD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,GAAG,MAAM,CAEzE;AAED,yDAAyD;AACzD,eAAO,MAAM,UAAU,IAAI,CAAC;AAE5B,qCAAqC;AACrC,eAAO,MAAM,SAAS,IAAI,CAAC;AAE3B,+CAA+C;AAC/C,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,0CAA0C;AAC1C,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,yEAAyE;AACzE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAE1D;AAED,qEAAqE;AACrE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAE3D;AAID,eAAO,MAAM,wBAAwB,EAAE,yBAOtC,CAAC"}
+{"version":3,"file":"trust-algebra.d.ts","sourceRoot":"","sources":["../src/trust-algebra.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,yBAAyB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAI7E;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAMrD,CAAC;AAEF,kDAAkD;AAClD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,GAAG,MAAM,CAEzE;AAED,yDAAyD;AACzD,eAAO,MAAM,UAAU,IAAI,CAAC;AAE5B,qCAAqC;AACrC,eAAO,MAAM,SAAS,IAAI,CAAC;AAE3B,+CAA+C;AAC/C,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,0CAA0C;AAC1C,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,yEAAyE;AACzE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAE1D;AAED,qEAAqE;AACrE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAE3D;AAmBD,eAAO,MAAM,0BAA0B,EAAE,yBAOxC,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,wBAAwB,EAAE,yBAAsD,CAAC"}

package/dist/trust-algebra.js

@@ -46,8 +46,23 @@ export function composeTrustChain(scores) {
 export function joinParallelRoutes(scores) {
     return scores.reduce(trustAdd, TRUST_ZERO);
 }
-// ── Default Thresholds ─────────────────────────────────────────────
-export const DEFAULT_TRUST_THRESHOLDS = {
+// ── Reference Thresholds ───────────────────────────────────────────
+//
+// These values are the motebit reference implementation's starting
+// point for agent-trust transitions — they prioritize, not compute.
+// The semiring algebra above (`trustAdd`, `trustMultiply`,
+// `TRUST_LEVEL_SCORES`, `TRUST_ZERO`, `TRUST_ONE`) IS protocol law —
+// two interoperating motebit implementations must compute trust the
+// same way. Transition thresholds are NOT protocol law — a federated
+// implementation may choose stricter or looser values and still
+// exchange trust scores correctly.
+//
+// The `REFERENCE_` prefix is the signal: "this is A reference default,
+// not THE mandated value." Exported from the permissive-floor package
+// so third-party integrators can adopt motebit's exact defaults if
+// they want to (one import, zero reinvention) — renaming alone
+// clarifies the role.
+export const REFERENCE_TRUST_THRESHOLDS = {
     promoteToVerified_minTasks: 5,
     promoteToVerified_minRate: 0.8,
     promoteToTrusted_minTasks: 20,
@@ -55,4 +70,19 @@ export const DEFAULT_TRUST_THRESHOLDS = {
     demote_belowRate: 0.5,
     demote_minTasks: 3,
 };
+/**
+ * @deprecated since 1.0.1, removed in 2.0.0. Use {@link REFERENCE_TRUST_THRESHOLDS} instead.
+ *
+ * Reason: the `DEFAULT_` prefix read as "THE value every motebit
+ * implementation uses," but trust-transition thresholds are motebit
+ * product tuning — they govern promotion and demotion policy, not
+ * protocol interop. A third-party motebit implementation may choose
+ * different thresholds and still interoperate correctly (the semiring
+ * algebra above is the interop contract). The `REFERENCE_` prefix
+ * signals "motebit's reference-implementation default; implementers
+ * MAY choose their own values." Rename-plus-deprecate so the naming
+ * correction ships without a breaking change; the old export is
+ * removed at 2.0.0.
+ */
+export const DEFAULT_TRUST_THRESHOLDS = REFERENCE_TRUST_THRESHOLDS;
 //# sourceMappingURL=trust-algebra.js.map

package/dist/trust-algebra.js.map

@@ -1 +1 @@
-{"version":3,"file":"trust-algebra.js","sourceRoot":"","sources":["../src/trust-algebra.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,uEAAuE;AAEvE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAA2B;IACxD,OAAO,EAAE,GAAG;IACZ,aAAa,EAAE,GAAG;IAClB,QAAQ,EAAE,GAAG;IACb,OAAO,EAAE,GAAG;IACZ,OAAO,EAAE,GAAG;CACb,CAAC;AAEF,kDAAkD;AAClD,MAAM,UAAU,iBAAiB,CAAC,KAA+B;IAC/D,OAAO,kBAAkB,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC;AAC1C,CAAC;AAED,yDAAyD;AACzD,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC;AAE5B,qCAAqC;AACrC,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAC;AAE3B,+CAA+C;AAC/C,MAAM,UAAU,QAAQ,CAAC,CAAS,EAAE,CAAS;IAC3C,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACxB,CAAC;AAED,0CAA0C;AAC1C,MAAM,UAAU,aAAa,CAAC,CAAS,EAAE,CAAS;IAChD,OAAO,CAAC,GAAG,CAAC,CAAC;AACf,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,iBAAiB,CAAC,MAAgB;IAChD,OAAO,MAAM,CAAC,MAAM,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;AACjD,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,kBAAkB,CAAC,MAAgB;IACjD,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;AAC7C,CAAC;AAED,sEAAsE;AAEtE,MAAM,CAAC,MAAM,wBAAwB,GAA8B;IACjE,0BAA0B,EAAE,CAAC;IAC7B,yBAAyB,EAAE,GAAG;IAC9B,yBAAyB,EAAE,EAAE;IAC7B,wBAAwB,EAAE,GAAG;IAC7B,gBAAgB,EAAE,GAAG;IACrB,eAAe,EAAE,CAAC;CACnB,CAAC"}
+{"version":3,"file":"trust-algebra.js","sourceRoot":"","sources":["../src/trust-algebra.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,uEAAuE;AAEvE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAA2B;IACxD,OAAO,EAAE,GAAG;IACZ,aAAa,EAAE,GAAG;IAClB,QAAQ,EAAE,GAAG;IACb,OAAO,EAAE,GAAG;IACZ,OAAO,EAAE,GAAG;CACb,CAAC;AAEF,kDAAkD;AAClD,MAAM,UAAU,iBAAiB,CAAC,KAA+B;IAC/D,OAAO,kBAAkB,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC;AAC1C,CAAC;AAED,yDAAyD;AACzD,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC;AAE5B,qCAAqC;AACrC,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAC;AAE3B,+CAA+C;AAC/C,MAAM,UAAU,QAAQ,CAAC,CAAS,EAAE,CAAS;IAC3C,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACxB,CAAC;AAED,0CAA0C;AAC1C,MAAM,UAAU,aAAa,CAAC,CAAS,EAAE,CAAS;IAChD,OAAO,CAAC,GAAG,CAAC,CAAC;AACf,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,iBAAiB,CAAC,MAAgB;IAChD,OAAO,MAAM,CAAC,MAAM,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;AACjD,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,kBAAkB,CAAC,MAAgB;IACjD,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;AAC7C,CAAC;AAED,sEAAsE;AACtE,EAAE;AACF,mEAAmE;AACnE,oEAAoE;AACpE,2DAA2D;AAC3D,qEAAqE;AACrE,oEAAoE;AACpE,qEAAqE;AACrE,gEAAgE;AAChE,mCAAmC;AACnC,EAAE;AACF,uEAAuE;AACvE,sEAAsE;AACtE,mEAAmE;AACnE,+DAA+D;AAC/D,sBAAsB;AAEtB,MAAM,CAAC,MAAM,0BAA0B,GAA8B;IACnE,0BAA0B,EAAE,CAAC;IAC7B,yBAAyB,EAAE,GAAG;IAC9B,yBAAyB,EAAE,EAAE;IAC7B,wBAAwB,EAAE,GAAG;IAC7B,gBAAgB,EAAE,GAAG;IACrB,eAAe,EAAE,CAAC;CACnB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAA8B,0BAA0B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motebit/protocol",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Motebit protocol — identity, receipts, credentials, delegation, settlement, and trust algebra for sovereign AI agents. Types, semirings, routing primitives. Apache-2.0, zero dependencies.",
   "type": "module",
   "main": "./dist/index.js",