@deepwatch/dsh-contracts 0.1.0

package/lib/readiness.js

@@ -0,0 +1,209 @@
+/**
+ * Whether a role can actually run, kept as four separate facts.
+ *
+ * This module exists because they were one. A provider row showed a green dot
+ * the moment a credential was saved, and a person reasonably read that as "the
+ * product is ready" — so they typed a prompt, and the runtime routed it to a
+ * provider they had never configured, failed on a missing environment
+ * variable, and left a failed turn in their session. Every step of that was a
+ * consequence of one indicator standing for four different questions:
+ *
+ *   1. is there a credential?          {@link ProviderCredentialStatus}
+ *   2. does the provider answer?       {@link ProviderReachability}
+ *   3. is a model chosen?              {@link ModelSelectionStatus}
+ *   4. is a role bound and runnable?   {@link RoleBindingStatus}
+ *
+ * A credential is the *first* of those and implies none of the others.
+ * {@link roleReadiness} is the only thing in this product allowed to answer
+ * "ready", and it requires all four to line up, plus a route that supports the
+ * role and a policy state that permits the request.
+ *
+ * **Nothing here ever carries secret material.** Not a value, not a prefix, a
+ * suffix, a length or a hash. A credential appears in these types only as a
+ * *reference* — an opaque handle the Host can resolve — and as a status word.
+ * `configured_unverified` is the honest state after a save: something is
+ * stored, and nobody has asked the provider whether it works.
+ *
+ * Verification is deliberately not automatic. Saving a credential must not
+ * quietly spend a request, and discovering models must be distinguishable from
+ * a billable completion — so both are user actions with their own results, and
+ * {@link ProviderReachability} stays `unknown` until one of them runs.
+ *
+ * @module @deepwatch/dsh-contracts/readiness
+ */
+/**
+ * The order blockers are reported in.
+ *
+ * Not alphabetical and not arbitrary: it is the order a person has to fix them
+ * in. Telling somebody their model is unavailable when they have not chosen a
+ * provider sends them to the wrong screen.
+ */
+const BLOCKER_ORDER = [
+    'no_binding',
+    'provider_unknown',
+    'credential_absent',
+    'credential_inaccessible',
+    'credential_rejected',
+    'model_unset',
+    'model_invalid',
+    'model_unavailable',
+    'provider_untested',
+    'provider_unreachable',
+    'provider_rate_limited',
+    'route_lacks_role',
+    'modality_unsupported',
+    'contract_mismatch',
+    'consent_required',
+    'policy_forbids',
+];
+/**
+ * Whether a role can run, and if not, exactly what is missing.
+ *
+ * The single gate. A caller may not assemble "ready" from parts: every surface
+ * that shows readiness, and both halves of preflight, ask this function, so
+ * there is one definition of executable and it is testable on its own.
+ *
+ * @param inputs - every fact that bears on the decision.
+ * @param role - the role being asked about.
+ * @returns the status and the blockers, in the order they must be fixed.
+ */
+export function roleReadiness(role, inputs) {
+    const found = new Set();
+    const { binding, route } = inputs;
+    if (binding === null) {
+        found.add('no_binding');
+    }
+    else {
+        if (route === null)
+            found.add('provider_unknown');
+        if (inputs.credential === 'absent')
+            found.add('credential_absent');
+        if (inputs.credential === 'inaccessible')
+            found.add('credential_inaccessible');
+        if (inputs.credential === 'rejected')
+            found.add('credential_rejected');
+        if (inputs.credential === 'configured_unverified')
+            found.add('provider_untested');
+        // A rejected credential is also what an `unauthorized` probe reports; both
+        // are the same missing step for a person, so they collapse to one blocker.
+        if (inputs.reachability === 'unauthorized')
+            found.add('credential_rejected');
+        if (inputs.reachability === 'unknown')
+            found.add('provider_untested');
+        if (inputs.reachability === 'unreachable')
+            found.add('provider_unreachable');
+        if (inputs.reachability === 'rate_limited')
+            found.add('provider_rate_limited');
+        if (inputs.model === 'none' || binding.model === '')
+            found.add('model_unset');
+        if (inputs.model === 'invalid')
+            found.add('model_invalid');
+        if (inputs.model === 'unavailable')
+            found.add('model_unavailable');
+        if (route !== null) {
+            if (!route.roles.includes(role))
+                found.add('route_lacks_role');
+            const supported = new Set(route.modalities);
+            if (!binding.modalities.every(modality => supported.has(modality))) {
+                found.add('modality_unsupported');
+            }
+        }
+        if (!inputs.contractMatches)
+            found.add('contract_mismatch');
+        if (!inputs.consentGranted)
+            found.add('consent_required');
+        if (!inputs.policyPermits)
+            found.add('policy_forbids');
+    }
+    const blockers = BLOCKER_ORDER.filter(blocker => found.has(blocker));
+    if (blockers.length === 0) {
+        return { role, status: 'executable', blockers: [], primaryBlocker: null };
+    }
+    // `unbound` and `blocked` are different answers to "what do I do now?": one
+    // needs a first choice, the other needs something repaired.
+    const status = binding === null
+        ? 'unbound'
+        : blockers.every(blocker => blocker === 'provider_untested')
+            ? 'bound_unverified'
+            : 'blocked';
+    return { role, status, blockers, primaryBlocker: blockers[0] ?? null };
+}
+/**
+ * Whether a role may be described to a person as ready.
+ *
+ * A helper rather than a comparison at each call site, because "ready" is
+ * exactly the word this whole module exists to stop being used loosely.
+ */
+export function isExecutable(readiness) {
+    return readiness.status === 'executable';
+}
+/** What a person should be told to do about one blocker, in their words. */
+const BLOCKER_COPY = {
+    no_binding: 'Choose a provider and model for this capability.',
+    provider_unknown: 'The bound provider is no longer available. Choose another.',
+    credential_absent: 'Add a credential for this provider.',
+    credential_inaccessible: 'The saved credential could not be read. Save it again.',
+    credential_rejected: 'The provider rejected the saved credential. Update it.',
+    provider_untested: 'Run the provider test before using this capability.',
+    provider_unreachable: 'The provider did not answer. Check the network and try again.',
+    provider_rate_limited: 'The provider rate-limited the test. Wait, then try again.',
+    model_unset: 'Choose a model for this capability.',
+    model_invalid: 'The chosen model is not valid for this provider. Choose another.',
+    model_unavailable: 'The provider no longer offers the chosen model. Choose another.',
+    route_lacks_role: 'This provider cannot serve this capability. Choose another.',
+    modality_unsupported: 'This model does not support what this capability needs.',
+    contract_mismatch: 'This version of DeepWatch cannot talk to that provider.',
+    consent_required: 'This capability needs a consent that has not been granted.',
+    policy_forbids: 'Policy on this machine forbids this request.',
+};
+/**
+ * One sentence a person can act on, for the blocker that matters most.
+ *
+ * Deliberately free of route ids, package names and environment variables:
+ * those belong in Diagnostics, and a person reading their first error should
+ * be told what to do rather than what broke internally.
+ */
+export function blockerMessage(readiness) {
+    const blocker = readiness.primaryBlocker;
+    return blocker === null ? null : BLOCKER_COPY[blocker];
+}
+/**
+ * Whether a status word may be drawn with the affordance that reads as "good".
+ *
+ * Only a proved binding earns it. `bound_unverified` deliberately does not:
+ * that is the state a green dot used to claim, and claiming it is what sent a
+ * prompt to an unconfigured provider.
+ */
+export function isPositiveBindingStatus(status) {
+    return status === 'executable';
+}
+/**
+ * The accessible label for a status, so colour is never the only signal.
+ *
+ * Every surface uses these words, so a screen reader and a sighted reader are
+ * told the same thing, and a red or green dot is decoration on top of text
+ * rather than the fact itself.
+ */
+export const BINDING_STATUS_LABEL = {
+    unbound: 'Not configured',
+    bound_unverified: 'Configured · not tested',
+    executable: 'Ready',
+    blocked: 'Blocked',
+};
+/** The accessible label for a credential status. */
+export const CREDENTIAL_STATUS_LABEL = {
+    absent: 'No credential',
+    configured_unverified: 'Credential saved · not yet assigned',
+    verified: 'Credential accepted',
+    rejected: 'Credential rejected',
+    inaccessible: 'Credential unreadable',
+};
+/** The accessible label for provider reachability. */
+export const REACHABILITY_LABEL = {
+    unknown: 'Not tested',
+    reachable: 'Answered',
+    unreachable: 'No answer',
+    rate_limited: 'Rate limited',
+    unauthorized: 'Rejected the credential',
+};
+//# sourceMappingURL=readiness.js.map

package/lib/workspace.d.ts

@@ -0,0 +1,141 @@
+/**
+ * The one resolved workspace every layer agrees on.
+ *
+ * A real owner session created `owner-test/totals.json` correctly and then
+ * could not be verified, because three layers each answered "which directory
+ * is this relative path in?" from a different place:
+ *
+ * - the agent's filesystem tools resolved against the Harness session
+ *   workspace, which the Harness derives from *its own process cwd*;
+ * - Watch Core was spawned with an empty `cwd`, so it inherited whatever the
+ *   Host happened to be started from;
+ * - the verifier, given no `workingDir`, fell back to `Path(".")` — the Core
+ *   process's cwd, which was neither of the above.
+ *
+ * Every one of those defaults is individually reasonable and the combination
+ * is a product that writes a file it cannot then find. The file landed outside
+ * every root the verifier would look in, so the honest answer was
+ * `INCONCLUSIVE` — correct, and useless.
+ *
+ * The fix is not to widen the verifier until it can see the file. It is to
+ * make the question have one answer. A {@link WorkspaceContext} is that
+ * answer: one absolute, traversal-resolved root, established once at launch
+ * and handed to the filesystem tools, the shell, Watch policy, the verifier,
+ * the evidence resolver, receipts, the Library projection and the session UI.
+ *
+ * **Fail closed.** {@link requireWorkspace} throws rather than inventing a
+ * root. A layer that cannot say where it is must stop and say so, because the
+ * alternative is what shipped: a silent default that looks like it worked.
+ *
+ * @module @deepwatch/dsh-contracts/workspace
+ */
+import { type PathRoots } from './paths.js';
+/** Environment variable naming the canonical workspace for a composed run. */
+export declare const WORKSPACE_ENV = "DEEPWATCH_WORKSPACE";
+/**
+ * One workspace, resolved once.
+ *
+ * `root` is absolute, separator-normalised and traversal-resolved, so two
+ * layers comparing it are comparing the same string rather than two spellings
+ * of one directory.
+ */
+export interface WorkspaceContext {
+    /** The canonical absolute root. Never rendered to a person or a model. */
+    readonly root: string;
+    /** How this root was chosen, for a diagnostic that can be acted on. */
+    readonly origin: WorkspaceOrigin;
+    /** Redaction roots, with the workspace already registered. */
+    readonly roots: PathRoots;
+}
+/**
+ * Where a canonical workspace came from.
+ *
+ * Recorded because "the workspace is wrong" and "there was no workspace and
+ * something guessed" are different bugs with different fixes, and the failed
+ * owner session could not tell them apart.
+ */
+export type WorkspaceOrigin = 
+/** A person named it: `deepwatch web --workspace <dir>`. */
+'flag'
+/** Inherited from a composed profile or launcher environment. */
+ | 'environment'
+/** The directory the command was invoked from, adopted deliberately. */
+ | 'invocation';
+/** Raised when a layer needs the canonical workspace and none was established. */
+export declare class WorkspaceNotEstablished extends Error {
+    readonly where: string;
+    constructor(where: string);
+}
+/** Raised when a relative path would resolve outside the canonical workspace. */
+export declare class WorkspaceEscape extends Error {
+    readonly attempted: string;
+    constructor(attempted: string);
+}
+/**
+ * Establish the canonical workspace from an absolute path.
+ *
+ * Rejects a relative candidate rather than resolving it against the current
+ * process cwd. Resolving here is what created the original defect: each layer
+ * had a different cwd, so "resolve it against cwd" produced three roots. A
+ * caller that only has a relative path has not yet decided which directory it
+ * means, and must decide before calling.
+ *
+ * @param candidate - an absolute local path.
+ * @param origin - how it was chosen, for diagnostics.
+ * @param extra - further roots to register for redaction (profile, dsh-home).
+ */
+export declare function establishWorkspace(candidate: string, origin: WorkspaceOrigin, extra?: PathRoots): WorkspaceContext;
+/**
+ * The established workspace, or a failure naming what to do about it.
+ *
+ * The fail-closed half of the contract. Call it from any layer that is about
+ * to resolve a relative path, so an unestablished workspace is a stop rather
+ * than a guess.
+ */
+export declare function requireWorkspace(context: WorkspaceContext | null | undefined, where: string): WorkspaceContext;
+/**
+ * Read the canonical workspace out of an environment.
+ *
+ * Returns null rather than throwing, so a caller can distinguish "nobody said"
+ * from "somebody said something unusable" and report the right one.
+ */
+export declare function workspaceFromEnvironment(env: Readonly<Record<string, string | undefined>>, extra?: PathRoots): WorkspaceContext | null;
+/**
+ * An absolute path for a workspace-relative one, or a refusal.
+ *
+ * The single resolution every layer routes through. `..` is resolved *before*
+ * the containment test, so `../elsewhere/notes.md` is refused rather than
+ * quietly landing a directory up — the check that a literal prefix comparison
+ * gets wrong.
+ *
+ * An already-absolute input is accepted only when it is inside the workspace,
+ * which keeps a caller from smuggling an outside path through a parameter
+ * documented as relative.
+ */
+export declare function resolveInWorkspace(context: WorkspaceContext, relative: string): string;
+/**
+ * Whether a path lands inside the canonical workspace.
+ *
+ * The containment question for a boundary that must answer before the side
+ * effect, not after it.
+ */
+export declare function insideWorkspace(context: WorkspaceContext, candidate: string): boolean;
+/**
+ * The workspace-relative, forward-slashed spelling of a path.
+ *
+ * What a receipt, a Library row and a verifier request should carry, so the
+ * same file is one string everywhere and no machine's directory names ride
+ * along. Returns null when the path is outside, so a caller cannot treat a
+ * failed conversion as a success and emit an absolute path.
+ */
+export declare function workspaceRelative(context: WorkspaceContext, candidate: string): string | null;
+/**
+ * Whether two layers agree about the workspace.
+ *
+ * The assertion a composed run makes at startup. Comparing normalised
+ * spellings rather than raw strings is the point: `D:\Ws` and `d:/Ws/` are one
+ * directory, and a mismatch reported between those two would send somebody
+ * looking for a bug that is not there.
+ */
+export declare function sameWorkspace(left: string, right: string): boolean;
+//# sourceMappingURL=workspace.d.ts.map

package/lib/workspace.js

@@ -0,0 +1,158 @@
+/**
+ * The one resolved workspace every layer agrees on.
+ *
+ * A real owner session created `owner-test/totals.json` correctly and then
+ * could not be verified, because three layers each answered "which directory
+ * is this relative path in?" from a different place:
+ *
+ * - the agent's filesystem tools resolved against the Harness session
+ *   workspace, which the Harness derives from *its own process cwd*;
+ * - Watch Core was spawned with an empty `cwd`, so it inherited whatever the
+ *   Host happened to be started from;
+ * - the verifier, given no `workingDir`, fell back to `Path(".")` — the Core
+ *   process's cwd, which was neither of the above.
+ *
+ * Every one of those defaults is individually reasonable and the combination
+ * is a product that writes a file it cannot then find. The file landed outside
+ * every root the verifier would look in, so the honest answer was
+ * `INCONCLUSIVE` — correct, and useless.
+ *
+ * The fix is not to widen the verifier until it can see the file. It is to
+ * make the question have one answer. A {@link WorkspaceContext} is that
+ * answer: one absolute, traversal-resolved root, established once at launch
+ * and handed to the filesystem tools, the shell, Watch policy, the verifier,
+ * the evidence resolver, receipts, the Library projection and the session UI.
+ *
+ * **Fail closed.** {@link requireWorkspace} throws rather than inventing a
+ * root. A layer that cannot say where it is must stop and say so, because the
+ * alternative is what shipped: a silent default that looks like it worked.
+ *
+ * @module @deepwatch/dsh-contracts/workspace
+ */
+import { containsPath, isAbsoluteLocalPath, normalisePath, relativeToRoot, resolveTraversal, } from './paths.js';
+/** Environment variable naming the canonical workspace for a composed run. */
+export const WORKSPACE_ENV = 'DEEPWATCH_WORKSPACE';
+/** Raised when a layer needs the canonical workspace and none was established. */
+export class WorkspaceNotEstablished extends Error {
+    where;
+    constructor(where) {
+        super(`${where} needs the canonical workspace and none was established. `
+            + 'Start DeepWatch with `deepwatch web --workspace <dir>`, or set '
+            + `${WORKSPACE_ENV} to an absolute path, so the agent's tools, Watch `
+            + 'containment and the verifier all resolve relative paths in one place.');
+        this.name = 'WorkspaceNotEstablished';
+        this.where = where;
+    }
+}
+/** Raised when a relative path would resolve outside the canonical workspace. */
+export class WorkspaceEscape extends Error {
+    attempted;
+    constructor(attempted) {
+        super(`"${attempted}" resolves outside the workspace. `
+            + 'Paths handed to the agent, the shell and the verifier are workspace-relative '
+            + 'by contract; nothing outside it is reachable by relative path.');
+        this.name = 'WorkspaceEscape';
+        this.attempted = attempted;
+    }
+}
+/**
+ * Establish the canonical workspace from an absolute path.
+ *
+ * Rejects a relative candidate rather than resolving it against the current
+ * process cwd. Resolving here is what created the original defect: each layer
+ * had a different cwd, so "resolve it against cwd" produced three roots. A
+ * caller that only has a relative path has not yet decided which directory it
+ * means, and must decide before calling.
+ *
+ * @param candidate - an absolute local path.
+ * @param origin - how it was chosen, for diagnostics.
+ * @param extra - further roots to register for redaction (profile, dsh-home).
+ */
+export function establishWorkspace(candidate, origin, extra = []) {
+    if (candidate === '' || !isAbsoluteLocalPath(candidate)) {
+        throw new Error(`A canonical workspace must be an absolute path; got "${candidate}". `
+            + 'Resolve it where the directory is actually known, not here — this module '
+            + 'has no cwd of its own on purpose.');
+    }
+    const root = resolveTraversal(candidate);
+    const workspaceRoot = { kind: 'workspace', path: root };
+    return { root, origin, roots: [workspaceRoot, ...extra] };
+}
+/**
+ * The established workspace, or a failure naming what to do about it.
+ *
+ * The fail-closed half of the contract. Call it from any layer that is about
+ * to resolve a relative path, so an unestablished workspace is a stop rather
+ * than a guess.
+ */
+export function requireWorkspace(context, where) {
+    if (context === null || context === undefined)
+        throw new WorkspaceNotEstablished(where);
+    return context;
+}
+/**
+ * Read the canonical workspace out of an environment.
+ *
+ * Returns null rather than throwing, so a caller can distinguish "nobody said"
+ * from "somebody said something unusable" and report the right one.
+ */
+export function workspaceFromEnvironment(env, extra = []) {
+    const named = env[WORKSPACE_ENV];
+    if (typeof named !== 'string' || named === '')
+        return null;
+    if (!isAbsoluteLocalPath(named))
+        return null;
+    return establishWorkspace(named, 'environment', extra);
+}
+/**
+ * An absolute path for a workspace-relative one, or a refusal.
+ *
+ * The single resolution every layer routes through. `..` is resolved *before*
+ * the containment test, so `../elsewhere/notes.md` is refused rather than
+ * quietly landing a directory up — the check that a literal prefix comparison
+ * gets wrong.
+ *
+ * An already-absolute input is accepted only when it is inside the workspace,
+ * which keeps a caller from smuggling an outside path through a parameter
+ * documented as relative.
+ */
+export function resolveInWorkspace(context, relative) {
+    const joined = isAbsoluteLocalPath(relative)
+        ? resolveTraversal(relative)
+        : resolveTraversal(`${context.root}/${relative}`);
+    if (!containsPath(context.root, joined))
+        throw new WorkspaceEscape(relative);
+    return joined;
+}
+/**
+ * Whether a path lands inside the canonical workspace.
+ *
+ * The containment question for a boundary that must answer before the side
+ * effect, not after it.
+ */
+export function insideWorkspace(context, candidate) {
+    return containsPath(context.root, candidate);
+}
+/**
+ * The workspace-relative, forward-slashed spelling of a path.
+ *
+ * What a receipt, a Library row and a verifier request should carry, so the
+ * same file is one string everywhere and no machine's directory names ride
+ * along. Returns null when the path is outside, so a caller cannot treat a
+ * failed conversion as a success and emit an absolute path.
+ */
+export function workspaceRelative(context, candidate) {
+    return relativeToRoot(resolveTraversal(candidate), context.root);
+}
+/**
+ * Whether two layers agree about the workspace.
+ *
+ * The assertion a composed run makes at startup. Comparing normalised
+ * spellings rather than raw strings is the point: `D:\Ws` and `d:/Ws/` are one
+ * directory, and a mismatch reported between those two would send somebody
+ * looking for a bug that is not there.
+ */
+export function sameWorkspace(left, right) {
+    return normalisePath(resolveTraversal(left)) === normalisePath(resolveTraversal(right));
+}
+//# sourceMappingURL=workspace.js.map

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@deepwatch/dsh-contracts",
+  "version": "0.1.0",
+  "description": "Watch Bridge wire contracts shared by the Host plugins and the browser halves",
+  "type": "module",
+  "license": "MIT",
+  "author": "Sayed Allam",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oxbshw/watch-skill.git",
+    "directory": "workspace/packages/watch/contracts"
+  },
+  "homepage": "https://github.com/oxbshw/watch-skill/tree/main/workspace#readme",
+  "bugs": {
+    "url": "https://github.com/oxbshw/watch-skill/issues"
+  },
+  "keywords": [
+    "deepwatch",
+    "deepseek-harness",
+    "watch-skill",
+    "contracts",
+    "protocol"
+  ],
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./identity": {
+      "types": "./lib/identity.d.ts",
+      "default": "./lib/identity.js"
+    },
+    "./query": {
+      "types": "./lib/query.d.ts",
+      "default": "./lib/query.js"
+    },
+    "./query/wire": {
+      "types": "./lib/query/wire.d.ts",
+      "default": "./lib/query/wire.js"
+    },
+    "./query/validate": {
+      "types": "./lib/query/validate.d.ts",
+      "default": "./lib/query/validate.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/**/*.js",
+    "lib/**/*.d.ts"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}