@deepwatch/dsh-contracts 0.1.0

package/lib/failures.js

@@ -0,0 +1,204 @@
+/**
+ * What a person is told when a conversation cannot run, and what they are not.
+ *
+ * A prompt failed and the Chat surface showed the reader
+ * `@deepseek-ai/dsh-system-prompt`, the route id `llm-deepseek`, the provider
+ * key `deepseek-official`, the environment variable `DEEPSEEK_API_KEY`, and a
+ * paragraph of sandbox-policy text. Every one of those is true, and not one of
+ * them told the reader what to do. Worse, two of them named a provider they had
+ * never chosen, so the message actively misled: it read as *DeepWatch is a
+ * DeepSeek product that is broken* rather than *nothing is bound yet*.
+ *
+ * This module draws the line. A raw provider or runtime failure is classified
+ * into one of a small closed set of {@link FailureKind}s, each of which becomes
+ * a card with a title, one sentence, and exactly one next action. The detailed
+ * technical facts are not destroyed — they go to Diagnostics and the Session
+ * Log, redacted — but they never render in an ordinary conversation.
+ *
+ * **Two rules hold everything here together.**
+ *
+ * The first is that a card carries no implementation identity.
+ * {@link assertNoInternalDisclosure} is the executable form of that rule, and
+ * it is applied to every card this module produces rather than trusted to
+ * review.
+ *
+ * The second is that nothing here ever carries credential material — and
+ * "material" includes the things people reach for when they are trying to be
+ * helpful about a key without printing it: a prefix, a suffix, a length, a
+ * fingerprint, a hash. A reader does not need to be told their key is 51
+ * characters long, and an attacker reading a shared screenshot does.
+ *
+ * @module @deepwatch/dsh-contracts/failures
+ */
+/** The card each kind renders as. */
+const CARDS = {
+    not_configured: {
+        title: 'Chat model is not configured',
+        detail: 'Choose a provider and a model, then assign one to Chat. Nothing is sent until you do.',
+        action: 'Choose models and roles',
+        target: 'role-bindings',
+    },
+    not_tested: {
+        title: 'Chat provider has not been tested',
+        detail: 'The provider and model are assigned, but no provider request has succeeded yet.',
+        action: 'Run provider test',
+        target: 'role-bindings',
+    },
+    credential_unavailable: {
+        title: 'Credential is unavailable',
+        detail: 'A credential is assigned to this provider, and it could not be read on this machine.',
+        action: 'Review the provider credential',
+        target: 'provider-credential',
+    },
+    credential_rejected: {
+        title: 'Provider rejected the credential',
+        detail: 'The provider answered and would not accept the credential saved for it.',
+        action: 'Update the provider credential',
+        target: 'provider-credential',
+    },
+    model_unavailable: {
+        title: 'Model is no longer available',
+        detail: 'The provider no longer offers the model assigned to this capability.',
+        action: 'Choose another model',
+        target: 'model-selection',
+    },
+    provider_unreachable: {
+        title: 'Provider is temporarily unreachable',
+        detail: 'No usable answer came back from the provider. Nothing was charged and no turn was recorded.',
+        action: 'Try again',
+        target: 'retry',
+    },
+    rate_limited: {
+        title: 'Request was rate-limited',
+        detail: 'The provider declined this request for rate reasons. Waiting and retrying usually clears it.',
+        action: 'Try again',
+        target: 'retry',
+    },
+    policy_forbids: {
+        title: 'This machine’s policy blocked the request',
+        detail: 'A policy in force here does not permit this request. Diagnostics records which one.',
+        action: 'Open Diagnostics',
+        target: 'diagnostics',
+    },
+    unavailable: {
+        title: 'The request could not be completed',
+        detail: 'Something went wrong before a reply could be produced. Diagnostics has the detail.',
+        action: 'Open Diagnostics',
+        target: 'diagnostics',
+    },
+};
+/**
+ * The card for one kind.
+ *
+ * @param kind - the classified failure.
+ * @param hasDiagnostics - whether a redacted record was written for it.
+ * @returns a card safe to render in an ordinary conversation.
+ */
+export function failureCard(kind, hasDiagnostics = true) {
+    const card = CARDS[kind];
+    return { kind, ...card, hasDiagnostics };
+}
+/**
+ * The card a readiness blocker becomes.
+ *
+ * The two vocabularies are separate because they answer different questions —
+ * a blocker is "what is missing", a card is "what a person sees when they tried
+ * anyway" — and this is the one place they are joined, so a blocker can never
+ * reach a reader with no card defined for it.
+ */
+export function cardForBlocker(blocker) {
+    const kind = blocker === 'credential_inaccessible'
+        ? 'credential_unavailable'
+        : blocker === 'provider_untested'
+            ? 'not_tested'
+            : blocker === 'credential_rejected'
+                ? 'credential_rejected'
+                : blocker === 'provider_unreachable'
+                    ? 'provider_unreachable'
+                    : blocker === 'provider_rate_limited'
+                        ? 'rate_limited'
+                        : blocker === 'model_unavailable' || blocker === 'model_invalid'
+                            ? 'model_unavailable'
+                            : blocker === 'policy_forbids' || blocker === 'consent_required'
+                                ? 'policy_forbids'
+                                : 'not_configured';
+    return failureCard(kind);
+}
+/**
+ * Classify a raw failure without letting its words through.
+ *
+ * The input is read for *signals* — an HTTP status, a taxonomy code the
+ * Harness already normalised — and the output is a kind. The raw text is
+ * never returned, never embedded, and never partially quoted, because a
+ * provider's message is exactly where the internal identifiers come from.
+ *
+ * @param signal - what the runtime managed to normalise about the failure.
+ * @returns the kind a reader is told about.
+ */
+export function classifyFailure(signal) {
+    const { status, code } = signal;
+    if (code === 'MISSING_CREDENTIAL')
+        return 'credential_unavailable';
+    if (code === 'NO_ADAPTER' || code === 'MODEL_NOT_FOUND')
+        return 'model_unavailable';
+    if (code === 'AUTH')
+        return 'credential_rejected';
+    if (code === 'RATE_LIMIT')
+        return 'rate_limited';
+    if (status === 401 || status === 403)
+        return 'credential_rejected';
+    if (status === 404)
+        return 'model_unavailable';
+    if (status === 429)
+        return 'rate_limited';
+    if (status !== undefined && status >= 500)
+        return 'provider_unreachable';
+    return 'unavailable';
+}
+/**
+ * Implementation identity that may not appear in an ordinary conversation.
+ *
+ * Each of these was on screen when a person's first prompt failed. They are
+ * matched as *shapes* rather than as a list of literals, because the list
+ * would go stale on the next baseline bump while the shapes — a scoped package
+ * name, an adapter route id, a screaming-snake environment variable — do not.
+ */
+const INTERNAL_SHAPES = [
+    { what: 'a scoped package name', pattern: /@(?:deepseek-ai|deepwatch|earendil-works)\/[a-z0-9-]+/i },
+    { what: 'an adapter route id', pattern: /\bllm-[a-z0-9-]+\b/i },
+    { what: 'a provider route key', pattern: /\b[a-z0-9]+-official\b/i },
+    { what: 'an environment variable name', pattern: /\b[A-Z][A-Z0-9]*_(?:API_KEY|KEY|TOKEN|SECRET|BASE_URL)\b/ },
+    { what: 'a stack frame', pattern: /\bat\s+[\w$.<>]+\s+\([^)]*:\d+:\d+\)/ },
+    { what: 'a module specifier', pattern: /\b(?:node|file):[/\\]{2}?[^\s"']+/i },
+    { what: 'a sandbox or approval policy identifier', pattern: /\b(?:sandbox|approval)Policy\b|\bpolicy:[a-z-]+/i },
+];
+/**
+ * Throw when text bound for an ordinary conversation carries an internal name.
+ *
+ * Applied to cards at construction rather than to the screen at review time.
+ * The failure it prevents is not hypothetical: every shape above is one that
+ * actually reached a reader, and the reason each got there was that some layer
+ * passed a provider or runtime string through "just this once".
+ *
+ * @param where - the surface being guarded, so a failure says what to fix.
+ * @param text - the candidate copy.
+ */
+export function assertNoInternalDisclosure(where, text) {
+    for (const { what, pattern } of INTERNAL_SHAPES) {
+        const found = pattern.exec(text);
+        if (found === null)
+            continue;
+        throw new Error(`${where} carries ${what} (${found[0]}). Implementation identity belongs in `
+            + 'Diagnostics, not in a conversation.');
+    }
+}
+/**
+ * Whether a card is safe to render, as a boolean rather than a throw.
+ *
+ * The same check for callers that are validating a table of copy rather than
+ * building one value — a test over every kind, typically.
+ */
+export function isDisclosureSafe(text) {
+    return !INTERNAL_SHAPES.some(shape => shape.pattern.test(text));
+}
+//# sourceMappingURL=failures.js.map

package/lib/identity.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Content identity, as Watch Core defines it.
+ *
+ * This is a mirror, not a second algorithm. `src/watch_skill/identity.py` is
+ * the source of truth, and it exists because of a specific defect: a video's id
+ * used to be `sha256(source_string)`, so overwriting `demo.mp4` returned
+ * yesterday's frames, OCR and cached answers for today's file with nothing in
+ * the reply admitting it. Core's answer was to stop treating the string as the
+ * identity and to name four things separately — the alias the user typed, the
+ * logical asset, the immutable revision keyed by content digest, and the cheap
+ * fingerprint that decides whether the digest has to be recomputed.
+ *
+ * The Workspace needs the same identity for the same reason. A Library record
+ * read from a file that carries no id of its own was briefly identified by a
+ * digest of its *path*, which fixed a disclosure problem and reintroduced the
+ * original one: move the bytes and they became a different record; overwrite
+ * them and they stayed the same one.
+ *
+ * So the functions below reproduce Core's exactly, including the material
+ * strings that go into each hash, and `tests/content-identity.test.mjs` runs
+ * the Python and asserts the two agree. A change to either side that is not
+ * made to both fails that test rather than silently splitting the namespace.
+ *
+ * Browser-safe: hashing goes through the Web Crypto API where the caller has
+ * bytes, and every id here is derived from a digest the caller already holds.
+ *
+ * @module @deepwatch/dsh-contracts/identity
+ */
+/** The one digest algorithm this contract uses. Mirrors `DIGEST_ALGORITHM`. */
+export declare const DIGEST_ALGORITHM = "sha256";
+/** Whether a value is a content digest this contract will carry. */
+export declare function isContentDigest(value: unknown): value is string;
+/**
+ * The id for one immutable version of some content.
+ *
+ * `identity.revision_id_for`. The material is `"<algorithm>:<digest>"`, so the
+ * algorithm is inside the hash and a future digest change cannot collide with
+ * this one.
+ */
+export declare function revisionIdFor(contentDigest: string, digest: (value: string) => string): string;
+/**
+ * The canonical id for the content itself.
+ *
+ * `identity.video_id_for_digest`. Named for content rather than for video
+ * here because the Library indexes documents, pages and captures through the
+ * same function; the material string is Core's, unchanged, so the two produce
+ * the same id for the same bytes.
+ *
+ * Sixteen hex characters with no prefix, which is both what Core hands out and
+ * an identifier `@deepwatch/dsh-contracts/query` will accept — so an id
+ * derived here can be sent straight back through a read that validates it.
+ */
+export declare function contentIdFor(contentDigest: string, digest: (value: string) => string): string;
+//# sourceMappingURL=identity.d.ts.map

package/lib/identity.js

@@ -0,0 +1,74 @@
+/**
+ * Content identity, as Watch Core defines it.
+ *
+ * This is a mirror, not a second algorithm. `src/watch_skill/identity.py` is
+ * the source of truth, and it exists because of a specific defect: a video's id
+ * used to be `sha256(source_string)`, so overwriting `demo.mp4` returned
+ * yesterday's frames, OCR and cached answers for today's file with nothing in
+ * the reply admitting it. Core's answer was to stop treating the string as the
+ * identity and to name four things separately — the alias the user typed, the
+ * logical asset, the immutable revision keyed by content digest, and the cheap
+ * fingerprint that decides whether the digest has to be recomputed.
+ *
+ * The Workspace needs the same identity for the same reason. A Library record
+ * read from a file that carries no id of its own was briefly identified by a
+ * digest of its *path*, which fixed a disclosure problem and reintroduced the
+ * original one: move the bytes and they became a different record; overwrite
+ * them and they stayed the same one.
+ *
+ * So the functions below reproduce Core's exactly, including the material
+ * strings that go into each hash, and `tests/content-identity.test.mjs` runs
+ * the Python and asserts the two agree. A change to either side that is not
+ * made to both fails that test rather than silently splitting the namespace.
+ *
+ * Browser-safe: hashing goes through the Web Crypto API where the caller has
+ * bytes, and every id here is derived from a digest the caller already holds.
+ *
+ * @module @deepwatch/dsh-contracts/identity
+ */
+/** The one digest algorithm this contract uses. Mirrors `DIGEST_ALGORITHM`. */
+export const DIGEST_ALGORITHM = 'sha256';
+/** Hex characters in a short id. Sixteen, as every Core id already is. */
+const SHORT_LENGTH = 16;
+/** Lowercase hex of a sha-256 digest, and nothing else. */
+const DIGEST = /^[0-9a-f]{64}$/;
+/** Whether a value is a content digest this contract will carry. */
+export function isContentDigest(value) {
+    return typeof value === 'string' && DIGEST.test(value);
+}
+/**
+ * `sha256(material)` truncated to sixteen hex characters, with a prefix.
+ *
+ * `identity._short`. The truncation is Core's and is kept: every id ever
+ * printed, cached, or written into an agent's notes is this width, and
+ * widening it here would split the namespace in the other direction.
+ */
+function short(prefix, material, digest) {
+    return prefix + digest(material).slice(0, SHORT_LENGTH);
+}
+/**
+ * The id for one immutable version of some content.
+ *
+ * `identity.revision_id_for`. The material is `"<algorithm>:<digest>"`, so the
+ * algorithm is inside the hash and a future digest change cannot collide with
+ * this one.
+ */
+export function revisionIdFor(contentDigest, digest) {
+    return short('rev_', `${DIGEST_ALGORITHM}:${contentDigest}`, digest);
+}
+/**
+ * The canonical id for the content itself.
+ *
+ * `identity.video_id_for_digest`. Named for content rather than for video
+ * here because the Library indexes documents, pages and captures through the
+ * same function; the material string is Core's, unchanged, so the two produce
+ * the same id for the same bytes.
+ *
+ * Sixteen hex characters with no prefix, which is both what Core hands out and
+ * an identifier `@deepwatch/dsh-contracts/query` will accept — so an id
+ * derived here can be sent straight back through a read that validates it.
+ */
+export function contentIdFor(contentDigest, digest) {
+    return digest(`watch-skill/v2/${contentDigest}`).slice(0, SHORT_LENGTH);
+}
+//# sourceMappingURL=identity.js.map