@deepwatch/dsh-contracts 0.1.0

package/lib/bindings.js

@@ -0,0 +1,333 @@
+/**
+ * What a person actually chose: which provider, which model, for which role.
+ *
+ * {@link module:@deepwatch/dsh-contracts/readiness} answers "can this run?"
+ * from four separate facts. This module is where three of those facts are
+ * *kept* — a durable document recording the decisions, so that reopening the
+ * product finds the same bindings rather than an empty screen and a composer
+ * pointed at somebody else's default.
+ *
+ * **A binding is a reference, never a credential.** The document below can be
+ * read by anything: it is written to the Harness's own settings file, it rides
+ * the settings RPC, it appears in Diagnostics, and it is included in a session
+ * export. None of that is safe unless the rule is absolute, so it is: the only
+ * credential-shaped field here is {@link RoleBindingRecord.credentialRef}, an
+ * opaque handle the Host resolves against its own store. No value, no prefix,
+ * no suffix, no length, no hash. {@link assertNoSecretMaterial} is the test
+ * this file is held to.
+ *
+ * **Nothing is bound implicitly.** There is no "default role", no inheritance
+ * from one role to another, and no provider that becomes bound because it was
+ * the only one configured. A role with no entry in {@link WatchBindings.roles}
+ * is unbound, and unbound means the composer refuses. That is the whole point
+ * of the module: the failure it exists to prevent was a product that treated a
+ * saved credential as a decision the person never made.
+ *
+ * @module @deepwatch/dsh-contracts/bindings
+ */
+/**
+ * The settings namespace this document lives in.
+ *
+ * A DeepWatch-owned section of the Harness's own user-settings document, which
+ * is what makes the binding durable, hot-reloaded and editable by hand without
+ * DeepWatch inventing a second configuration store beside the one the product
+ * already has.
+ */
+export const BINDINGS_NAMESPACE = 'watch-bindings';
+/**
+ * The document revision this build writes.
+ *
+ * Read forward, never rewritten in place: an older document is migrated on
+ * read and a newer one is refused rather than silently reinterpreted, because
+ * misreading a binding routes somebody's prompt somewhere they did not choose.
+ */
+export const BINDINGS_VERSION = 1;
+/**
+ * The roles a person can bind to a provider, in the order setup presents them.
+ *
+ * These ids are `RoleId`s from `@deepwatch/dsh-technology`, spelled here rather
+ * than imported because `contracts` is the package everything else depends on
+ * and must not depend on anything. `tests/bindings-store.test.mjs` asserts the
+ * two lists agree, so the duplication is checked rather than trusted -- one
+ * role vocabulary with a gate on it, instead of two that drift.
+ *
+ * It is a *subset*. `verifier`, `ocr_layout`, `reranking` and
+ * `speaker_diarization` are served by local engines rather than chosen from a
+ * provider catalogue, so offering them here would offer a choice that is not
+ * there.
+ *
+ * `agent_model` is first and is the only one the first conversation needs. The
+ * rest are progressive: a product that demanded five bindings before the first
+ * message would be a product nobody finished configuring.
+ */
+export const BINDABLE_ROLES = [
+    'agent_model', 'visual_perception', 'asr', 'audio_understanding', 'embeddings',
+];
+/** The role the first conversation needs, named once so nothing spells it twice. */
+export const PRIMARY_ROLE = 'agent_model';
+/**
+ * What each role is called on screen.
+ *
+ * `agent_model` is labelled **Chat**, and the difference is not cosmetic. A
+ * person configuring this product is not choosing an "agent model" -- they are
+ * choosing what answers them in the surface the Harness calls Chat, and every
+ * blocked-composer message and setup step has to name the thing they are
+ * looking at. The id stays `agent_model` because that is the vocabulary the
+ * descriptors and the routing rules already use.
+ */
+export const ROLE_LABEL = {
+    agent_model: 'Chat',
+    visual_perception: 'Visual perception',
+    asr: 'Speech to text',
+    audio_understanding: 'Audio understanding',
+    embeddings: 'Embeddings and retrieval',
+};
+/** Whether a string is a role this product binds. */
+export function isBindableRole(value) {
+    return BINDABLE_ROLES.includes(value);
+}
+/**
+ * What each role is for, in a person's words.
+ *
+ * Here rather than in a component because the setup flow, the Role Bindings
+ * screen and the blocked-composer card all name the same role, and three
+ * copies of this sentence would eventually be three different sentences.
+ */
+export const ROLE_PURPOSE = {
+    agent_model: 'Plans, reasons and writes. This is what answers you in a conversation.',
+    visual_perception: 'Reads what is on screen or in a frame.',
+    asr: 'Speech to text, with timings a citation can point at.',
+    audio_understanding: 'Non-speech audio: events, tone, music.',
+    embeddings: 'Search over the library and over memory.',
+};
+/** The modalities each role's work actually needs a route to support. */
+export const ROLE_MODALITIES = {
+    agent_model: ['text'],
+    visual_perception: ['vision'],
+    asr: ['audio'],
+    audio_understanding: ['audio'],
+    embeddings: ['embedding'],
+};
+/** The actors a stored document may name. */
+export const BINDING_ACTORS = ['person', 'setup', 'unknown'];
+/** Whether a stored value is an actor this build understands. */
+export function isBindingActor(value) {
+    return typeof value === 'string' && BINDING_ACTORS.includes(value);
+}
+/** The document a profile that has never been configured has. */
+export const EMPTY_BINDINGS = { version: BINDINGS_VERSION, roles: {} };
+/**
+ * A model id worth storing.
+ *
+ * Deliberately permissive about shape — provider model ids are provider-owned
+ * and this product does not get to decide that `openai/gpt-4o` is malformed —
+ * and deliberately strict about the things that make a stored value dangerous:
+ * control characters, newlines and absurd length, all of which arrive from a
+ * hand-edited settings file rather than from the picker.
+ */
+export function isStorableId(value) {
+    return typeof value === 'string'
+        && value !== ''
+        && value.length <= 200
+        // eslint-disable-next-line no-control-regex -- rejecting these is the point.
+        && !/[\u0000-\u001f\u007f]/.test(value);
+}
+/**
+ * Read a stored document, keeping only what is well-formed.
+ *
+ * A hand-edited settings file is a supported way to configure this product, so
+ * a malformed entry must not take the whole document with it: the bad role is
+ * dropped and the rest survive. Dropping is the safe direction — an unbound
+ * role refuses at the composer, where a person is told what to fix, whereas a
+ * half-read binding would route a prompt somewhere nobody chose.
+ *
+ * @param raw - whatever the settings document held.
+ * @returns a document this build can act on.
+ */
+export function readBindings(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return EMPTY_BINDINGS;
+    const record = raw;
+    // A document from a future build is not merged, not guessed at, and not
+    // partially honoured: the shape it uses is one this build has never seen.
+    if (typeof record.version === 'number' && record.version > BINDINGS_VERSION) {
+        return EMPTY_BINDINGS;
+    }
+    if (typeof record.roles !== 'object' || record.roles === null)
+        return EMPTY_BINDINGS;
+    const roles = {};
+    for (const [role, value] of Object.entries(record.roles)) {
+        if (!isBindableRole(role))
+            continue;
+        const entry = readBindingRecord(value);
+        if (entry !== null)
+            roles[role] = entry;
+    }
+    return { version: BINDINGS_VERSION, roles };
+}
+/** One entry, or null when it is not something this build can honour. */
+function readBindingRecord(value) {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const entry = value;
+    if (!isStorableId(entry['provider']) || !isStorableId(entry['model']))
+        return null;
+    const ref = entry['credentialRef'];
+    // A non-string reference is read as "no reference" rather than refused: the
+    // binding's provider and model are still the person's choice, and the Host
+    // reports an unresolvable credential as a blocker they can act on.
+    const credentialRef = typeof ref === 'string' && ref !== '' ? ref : null;
+    const boundAt = typeof entry['boundAt'] === 'string' ? entry['boundAt'] : '';
+    // Anything this build does not recognise reads as `unknown`, including the
+    // absence of the field. A document from an earlier version is unattributed,
+    // which is true, rather than attributed to a person who may not have written
+    // it.
+    const boundBy = isBindingActor(entry['boundBy']) ? entry['boundBy'] : 'unknown';
+    return {
+        provider: entry['provider'], model: entry['model'], credentialRef, boundAt, boundBy,
+    };
+}
+/**
+ * The document with one role bound, as a new value.
+ *
+ * Never mutates: the caller holds a snapshot it may still be rendering from,
+ * and a document edited underneath a React tree is a stale-render bug that
+ * shows somebody the binding they had a moment ago.
+ */
+export function withBinding(current, role, record) {
+    return { version: BINDINGS_VERSION, roles: { ...current.roles, [role]: record } };
+}
+/** The document with one role unbound. */
+export function withoutBinding(current, role) {
+    const roles = Object.fromEntries(Object.entries(current.roles).filter(([key]) => key !== role));
+    return { version: BINDINGS_VERSION, roles };
+}
+/**
+ * The readiness-shaped view of one stored role, or null when it is unbound.
+ *
+ * The join between this module and `readiness`: storage keeps records, the
+ * gate takes {@link RoleBinding}s, and this is the only place that converts
+ * one into the other — so the modalities a role is checked against always come
+ * from {@link ROLE_MODALITIES} rather than from whatever a call site guessed.
+ */
+export function bindingFor(bindings, role) {
+    const record = bindings.roles[role];
+    if (record === undefined)
+        return null;
+    return {
+        role,
+        provider: record.provider,
+        model: record.model,
+        credentialRef: record.credentialRef,
+        modalities: ROLE_MODALITIES[role],
+    };
+}
+/** Whether a role has a stored decision at all. Not whether it can run. */
+export function isBound(bindings, role) {
+    return bindings.roles[role] !== undefined;
+}
+/**
+ * Every provider a stored binding names, once each.
+ *
+ * What Settings uses to decide which providers to show credential state for:
+ * the ones a person actually pointed something at, rather than all
+ * thirty-seven routes the catalogue carries.
+ */
+export function boundProviders(bindings) {
+    const seen = new Set();
+    for (const record of Object.values(bindings.roles))
+        seen.add(record.provider);
+    return [...seen].sort();
+}
+/**
+ * Whether a provider/model pair is one this profile actually bound.
+ *
+ * The authoritative question, and deliberately the *narrow* one. It does not
+ * ask whether the route exists, whether a credential is stored, or whether the
+ * provider is reachable — those are the Host's to answer at the moment of the
+ * request. It asks the only thing a stored document can answer: did somebody
+ * choose this pair for something.
+ *
+ * That is what makes it usable as a gate at a routing boundary. A request for
+ * a pair nobody bound is a request nobody authorised, whatever the client that
+ * produced it believed — a stale tab holding a selection that has since been
+ * changed, or a caller that set one directly and skipped the screens.
+ *
+ * Any bound role counts, not only the one being served: a person who bound
+ * OpenRouter to Chat has authorised that route, and the title and compaction
+ * calls that ride the same selection are the same authorisation, not new ones.
+ *
+ * @param bindings - the stored document.
+ * @param provider - the route the request names.
+ * @param model - the model the request names.
+ * @returns whether some role in this profile is bound to exactly that pair.
+ */
+export function isRoutePermitted(bindings, provider, model) {
+    if (provider === '' || model === '')
+        return false;
+    return Object.values(bindings.roles).some(record => record.provider === provider && record.model === model);
+}
+/**
+ * Every distinct provider/model pair this profile bound, for a diagnostic.
+ *
+ * A refusal that says "this route is not bound" is not much use without the
+ * ability to say what *is*, and that list is a set of choices rather than
+ * anything sensitive — no credential, no reference, no host path.
+ */
+export function permittedRoutes(bindings) {
+    const seen = new Set();
+    for (const record of Object.values(bindings.roles)) {
+        seen.add(`${record.provider}/${record.model}`);
+    }
+    return [...seen].sort();
+}
+/**
+ * Patterns that must never appear in a stored binding.
+ *
+ * Not an exhaustive secret detector — there is no such thing — but a guard on
+ * the shapes a credential takes when somebody pastes one into a field meant to
+ * hold a reference.
+ *
+ * `OPENROUTER_API_KEY` is deliberately *not* one of them, and that distinction
+ * is the design rather than an omission: it is a reference — the name of a
+ * place the Host looks — and naming a place is exactly what `credentialRef` is
+ * for. A guard that refused it would refuse every legitimate binding, be
+ * switched off within a day, and stop catching what it was written for. What
+ * is refused is a *value*: the shapes a key has when the key itself is pasted.
+ */
+const SECRET_SHAPES = [
+    /\bsk-[A-Za-z0-9_-]{8,}/,
+    /\bsk_live_[A-Za-z0-9]{8,}/,
+    /\bBearer\s+[A-Za-z0-9._-]{8,}/i,
+    // A long run of mixed-case token characters. A reference is a name a person
+    // could read aloud; anything this long that is not one is a value somebody
+    // pasted where a name belongs.
+    /(?=[A-Za-z0-9+/_-]{32,})(?=[^\n]*[a-z])(?=[^\n]*[A-Z])(?=[^\n]*\d)[A-Za-z0-9+/_-]{32,}/,
+];
+/**
+ * Throw when a document about to be stored or shown carries secret material.
+ *
+ * A programming error rather than a runtime condition: every write path builds
+ * this document from a picker, so a value matching one of these means a code
+ * path has started copying a credential into a place that is read back in
+ * plain text. Failing loudly at the write is the only point where that is
+ * still cheap to fix.
+ *
+ * @param where - the surface being guarded, for a message that can be acted on.
+ * @param bindings - the document about to leave a trusted boundary.
+ */
+export function assertNoSecretMaterial(where, bindings) {
+    for (const [role, record] of Object.entries(bindings.roles)) {
+        for (const [field, value] of Object.entries(record)) {
+            if (typeof value !== 'string')
+                continue;
+            for (const shape of SECRET_SHAPES) {
+                if (!shape.test(value))
+                    continue;
+                throw new Error(`${where}: the ${role} binding's ${field} looks like credential material. `
+                    + 'A binding stores a reference the Host resolves, never a value.');
+            }
+        }
+    }
+}
+//# sourceMappingURL=bindings.js.map

package/lib/digests.d.ts

@@ -0,0 +1,77 @@
+/**
+ * The Watch Core contract digests this build was written against.
+ *
+ * ADR-004 makes the Pydantic models in `watch-skill` the semantic source of
+ * truth for the wire, and the TypeScript types in this package a face over
+ * them. The risk in that arrangement is drift: the engine adds a field, the
+ * Workspace keeps compiling, and the mismatch first shows up as a value that
+ * is quietly `undefined` in production.
+ *
+ * These digests close that. Watch Core reports the same values in its
+ * handshake, computed from the models themselves, and the Bridge compares them
+ * on connect. A family that disagrees disables the Watch features that depend
+ * on it and names both sides, instead of failing later somewhere unrelated.
+ *
+ * Regenerate with `python scripts/gen_bridge_schemas.py` in `watch-skill`, then
+ * copy the `families` block from `schemas/bridge/manifest.json`.
+ *
+ * @module @deepwatch/dsh-contracts/digests
+ */
+/** One contract family: a group of fields consumers break on together. */
+export type SchemaFamily = 'handshake' | 'evidence' | 'verification' | 'answer' | 'library' | 'error';
+/**
+ * Digests generated from Watch Core's Bridge wire models.
+ *
+ * Source: `schemas/bridge/manifest.json`, written by
+ * `python scripts/gen_bridge_schemas.py` from
+ * `watch_skill.surfaces.bridge.wire`. Core computes the same values at import
+ * and reports them in the handshake, so these two are one artifact seen from
+ * two sides rather than two lists that have to be kept in step by hand.
+ *
+ * A digest changes when a family's schema changes in a way that matters:
+ * hashing is over the canonical, key-sorted document, so a reordered field
+ * does not read as a breaking change and a renamed one does.
+ */
+export declare const EXPECTED_SCHEMA_DIGESTS: Readonly<Record<SchemaFamily, string>>;
+/**
+ * Which Watch capability each contract family is load-bearing for.
+ *
+ * Used to disable *only* the affected features on a mismatch. A changed
+ * `library` schema should not take verification offline, and vice versa.
+ */
+export declare const FAMILY_CAPABILITIES: Readonly<Record<SchemaFamily, readonly string[]>>;
+/** One family whose digest did not match. */
+export interface SchemaDrift {
+    readonly family: SchemaFamily;
+    /** What this build was written against. */
+    readonly expected: string;
+    /** What Watch Core reported, or null when it reported nothing for it. */
+    readonly actual: string | null;
+    /** Capabilities that must be treated as unavailable because of it. */
+    readonly affects: readonly string[];
+}
+/**
+ * Compare the handshake's digests against this build's.
+ *
+ * A family Watch Core does not report at all counts as drift with a null
+ * `actual`: an engine that has stopped publishing a digest is exactly as
+ * unverifiable as one publishing a different value, and treating silence as
+ * agreement is how this check would come to mean nothing.
+ *
+ * @param reported - the `schemaDigests` map from the handshake.
+ * @returns every family that disagrees, empty when the contract matches.
+ */
+export declare function detectSchemaDrift(reported: Readonly<Record<string, string>>): readonly SchemaDrift[];
+/**
+ * Whether an engine reporting no digests at all should be treated as drift.
+ *
+ * It should not. A Watch Core older than the schema manifest reports an empty
+ * map, and refusing to talk to it would break a working setup to enforce a
+ * check it predates. The Bridge surfaces that as "unverified contract" — a
+ * degraded, visible state — rather than as a mismatch it cannot substantiate.
+ *
+ * @param reported - the `schemaDigests` map from the handshake.
+ * @returns true when the engine published nothing to compare.
+ */
+export declare function isContractUnverified(reported: Readonly<Record<string, string>> | null | undefined): boolean;
+//# sourceMappingURL=digests.d.ts.map

package/lib/digests.js

@@ -0,0 +1,103 @@
+/**
+ * The Watch Core contract digests this build was written against.
+ *
+ * ADR-004 makes the Pydantic models in `watch-skill` the semantic source of
+ * truth for the wire, and the TypeScript types in this package a face over
+ * them. The risk in that arrangement is drift: the engine adds a field, the
+ * Workspace keeps compiling, and the mismatch first shows up as a value that
+ * is quietly `undefined` in production.
+ *
+ * These digests close that. Watch Core reports the same values in its
+ * handshake, computed from the models themselves, and the Bridge compares them
+ * on connect. A family that disagrees disables the Watch features that depend
+ * on it and names both sides, instead of failing later somewhere unrelated.
+ *
+ * Regenerate with `python scripts/gen_bridge_schemas.py` in `watch-skill`, then
+ * copy the `families` block from `schemas/bridge/manifest.json`.
+ *
+ * @module @deepwatch/dsh-contracts/digests
+ */
+/**
+ * Digests generated from Watch Core's Bridge wire models.
+ *
+ * Source: `schemas/bridge/manifest.json`, written by
+ * `python scripts/gen_bridge_schemas.py` from
+ * `watch_skill.surfaces.bridge.wire`. Core computes the same values at import
+ * and reports them in the handshake, so these two are one artifact seen from
+ * two sides rather than two lists that have to be kept in step by hand.
+ *
+ * A digest changes when a family's schema changes in a way that matters:
+ * hashing is over the canonical, key-sorted document, so a reordered field
+ * does not read as a breaking change and a renamed one does.
+ */
+export const EXPECTED_SCHEMA_DIGESTS = {
+    answer: 'sha256:2abc33bc76abe07486446bae94c70211',
+    error: 'sha256:f83b04be5dffc2dfab6963f071c7455a',
+    evidence: 'sha256:3facf1e0c00ffb61e9724d0a17b5d589',
+    handshake: 'sha256:215466e1a4d3ea526e71c5a162bf861b',
+    library: 'sha256:cb1a1721b33ccca2e25ea000fe41c7f1',
+    verification: 'sha256:0f381733ba98849b8335ad0fa1534534',
+};
+/**
+ * Which Watch capability each contract family is load-bearing for.
+ *
+ * Used to disable *only* the affected features on a mismatch. A changed
+ * `library` schema should not take verification offline, and vice versa.
+ */
+export const FAMILY_CAPABILITIES = {
+    handshake: ['watch.video.query', 'watch.library.search', 'watch.verification.run'],
+    evidence: ['watch.video.query', 'watch.evidence.resolve'],
+    verification: ['watch.verification.run'],
+    answer: ['watch.video.query'],
+    library: ['watch.library.search'],
+    error: [],
+};
+/**
+ * Compare the handshake's digests against this build's.
+ *
+ * A family Watch Core does not report at all counts as drift with a null
+ * `actual`: an engine that has stopped publishing a digest is exactly as
+ * unverifiable as one publishing a different value, and treating silence as
+ * agreement is how this check would come to mean nothing.
+ *
+ * @param reported - the `schemaDigests` map from the handshake.
+ * @returns every family that disagrees, empty when the contract matches.
+ */
+export function detectSchemaDrift(reported) {
+    const drift = [];
+    for (const [family, expected] of Object.entries(EXPECTED_SCHEMA_DIGESTS)) {
+        const actual = reported[family];
+        if (actual === expected)
+            continue;
+        drift.push({
+            family: family,
+            expected,
+            actual: actual ?? null,
+            affects: FAMILY_CAPABILITIES[family],
+        });
+    }
+    return drift;
+}
+/**
+ * Whether an engine reporting no digests at all should be treated as drift.
+ *
+ * It should not. A Watch Core older than the schema manifest reports an empty
+ * map, and refusing to talk to it would break a working setup to enforce a
+ * check it predates. The Bridge surfaces that as "unverified contract" — a
+ * degraded, visible state — rather than as a mismatch it cannot substantiate.
+ *
+ * @param reported - the `schemaDigests` map from the handshake.
+ * @returns true when the engine published nothing to compare.
+ */
+export function isContractUnverified(reported) {
+    // Absent and empty are the same answer: nothing was published to compare.
+    // The type says this map is always present, and the type does not survive
+    // the wire — this value came out of `JSON.parse` of whatever the engine
+    // actually sent. An engine that omits the field used to take `Object.keys`
+    // straight into a TypeError, which escaped `connect()` as an unhandled
+    // throw and lost the degraded state this function exists to produce.
+    if (reported === null || reported === undefined || typeof reported !== 'object')
+        return true;
+    return Object.keys(reported).length === 0;
+}
+//# sourceMappingURL=digests.js.map