@hasna/machines 0.0.23 → 0.0.24

package/README.md

@@ -57,15 +57,25 @@ should import `@hasna/machines/consumer`:
 ```ts
 import {
   MACHINES_CONSUMER_CONTRACT,
+  createMachineResolverSnapshot,
   discoverMachineTopology,
   getLocalMachineTopology,
   resolveMachineRoute,
+  resolveMachineWorkspace,
+  validateMachinesConsumerEnvelope,
 } from "@hasna/machines/consumer";
 
 console.log(MACHINES_CONSUMER_CONTRACT.schema_version);
 const topology = discoverMachineTopology();
 const local = getLocalMachineTopology();
 const route = resolveMachineRoute("spark01");
+const workspace = resolveMachineWorkspace({
+  machineId: "spark01",
+  projectId: "open-knowledge",
+  repoName: "open-knowledge",
+});
+const snapshot = createMachineResolverSnapshot({ route, workspace });
+console.log(validateMachinesConsumerEnvelope("resolver_snapshot", snapshot).ok);
 ```
 
 The SDK merges manifest entries, local heartbeats, SSH route hints, and
@@ -74,11 +84,19 @@ The SDK merges manifest entries, local heartbeats, SSH route hints, and
 when present, and fall back to local probes or app-local machine registries when
 it is absent.
 
-Topology, route, workspace, and compatibility JSON include `schema_version`,
-package version metadata, and capability flags. The current consumer contract
-version is `1`; the exported `MACHINES_CONSUMER_CONTRACT` records the stable
-entrypoint, envelope names, and stable exports used by downstream apps such as
-`@hasna/knowledge`.
+Topology, route, workspace, compatibility, and resolver-snapshot JSON include
+`schema_version`, package version metadata, capability flags, and cacheability
+metadata where downstream apps may persist resolver evidence. The current
+consumer contract version is `1`; the exported `MACHINES_CONSUMER_CONTRACT`
+records the stable entrypoint, envelope names, schema artifact, field
+capabilities, default resolver TTL, and stable exports used by downstream apps
+such as `@hasna/knowledge`.
+
+The package includes `schemas/machines-consumer.schema.json` and also exports
+`MACHINES_CONSUMER_SCHEMA_BUNDLE`, `getMachinesConsumerSchemaBundle()`, and
+`validateMachinesConsumerEnvelope()`. Downstream apps can use these helpers to
+validate route, workspace, compatibility, and resolver-snapshot envelopes
+without importing CLI, MCP, agent, installer, or storage-heavy internals.
 
 The package also ships a downstream conformance fixture for consumers that want
 to verify their optional adapter boundary without copying app-specific smoke

package/dist/cli/index.js

@@ -7628,13 +7628,18 @@ import { spawnSync } from "child_process";
 init_paths();
 var MACHINES_CONSUMER_CONTRACT_VERSION = 1;
 var MACHINES_PACKAGE_NAME = "@hasna/machines";
+var DEFAULT_MACHINE_RESOLVER_TTL_MS = 24 * 60 * 60 * 1000;
 var MACHINES_CONSUMER_CAPABILITIES = {
   topology: true,
   compatibility: true,
   route_resolution: true,
   cli_json_fallback: true,
   workspace_path_mapping: true,
-  workspace_diagnostics: true
+  workspace_diagnostics: true,
+  schema_artifacts: true,
+  cacheability_metadata: true,
+  resolver_snapshots: true,
+  field_capability_descriptors: true
 };
 function getMachinesConsumerCapabilities() {
   return { ...MACHINES_CONSUMER_CAPABILITIES };
@@ -7905,11 +7910,69 @@ function routeConfidence(input) {
     return "low";
   return "none";
 }
+function addMilliseconds(date, milliseconds) {
+  return new Date(date.getTime() + milliseconds).toISOString();
+}
+function routeAuthority(input) {
+  if (!input.machine)
+    return "unresolved";
+  if (input.matchedBy === "fallback")
+    return "fallback";
+  if (input.selectedHint?.kind === "local")
+    return "live_topology";
+  if (input.selectedHint?.kind === "tailscale" || input.machine.tailscale.online !== null)
+    return "live_topology";
+  if (input.machine.manifest_declared)
+    return "manifest";
+  return "open-machines";
+}
+function workspaceAuthority(paths) {
+  const sources = [paths.workspace_root.source, paths.project_root.source, paths.open_files_root.source];
+  if (sources.some((source) => source === "argument"))
+    return "argument";
+  if (sources.some((source) => source === "manifest_metadata"))
+    return "manifest_metadata";
+  if (sources.some((source) => source === "manifest"))
+    return "manifest";
+  if (sources.some((source) => source === "inferred"))
+    return "inferred";
+  if (sources.every((source) => source === "unresolved"))
+    return "unresolved";
+  return "open-machines";
+}
+function cacheability(input) {
+  const ttlMs = input.ttlMs === undefined ? DEFAULT_MACHINE_RESOLVER_TTL_MS : input.ttlMs;
+  const expiresAt = typeof ttlMs === "number" && ttlMs > 0 ? addMilliseconds(input.observedAt, ttlMs) : null;
+  const stale = expiresAt ? input.now.getTime() > new Date(expiresAt).getTime() : false;
+  const confidenceCacheable = input.confidence !== "none" && input.confidence !== "low";
+  const cacheable = input.ok && confidenceCacheable && !stale && input.authority !== "unresolved";
+  const reasons = [...input.reasons];
+  if (!input.ok)
+    reasons.push("resolver_not_ok");
+  if (!confidenceCacheable)
+    reasons.push(`low_confidence:${input.confidence}`);
+  if (stale)
+    reasons.push("stale");
+  if (input.authority === "unresolved")
+    reasons.push("unresolved_authority");
+  return {
+    observed_at: input.observedAt.toISOString(),
+    verified_at: input.ok ? input.now.toISOString() : null,
+    expires_at: expiresAt,
+    ttl_ms: typeof ttlMs === "number" && ttlMs > 0 ? ttlMs : null,
+    source_authority: input.authority,
+    confidence: input.confidence,
+    cacheable,
+    stale,
+    reasons: [...new Set(reasons)].sort()
+  };
+}
 function resolveMachineRoute(machineId, options = {}) {
+  const now = options.now ?? new Date;
   const topology = options.topology ?? discoverMachineTopology(options);
   const warnings = [...topology.warnings];
   const { machine, matchedBy } = findRouteMachine(topology, machineId);
-  const generatedAt = (options.now ?? new Date).toISOString();
+  const generatedAt = now.toISOString();
   if (!machine) {
     warnings.push(`machine_not_found:${machineId}`);
     return {
@@ -7933,16 +7996,27 @@ function resolveMachineRoute(machineId, options = {}) {
         tailscale_online: null,
         selected_hint: null
       },
+      cacheability: cacheability({
+        ok: false,
+        observedAt: now,
+        now,
+        ttlMs: options.resolverTtlMs,
+        authority: "unresolved",
+        confidence: "none",
+        reasons: [`machine_not_found:${machineId}`]
+      }),
       warnings
     };
   }
   const selectedHint = selectRouteHint(machine.route_hints);
   const route = selectedHint?.kind ?? machine.ssh.route ?? "unknown";
   const local = route === "local" || machine.machine_id === topology.local_machine_id;
+  const confidence = routeConfidence({ machine, hint: selectedHint, matchedBy });
+  const ok = Boolean(selectedHint?.target);
   return {
     schema_version: MACHINES_CONSUMER_CONTRACT_VERSION,
     package: topology.package,
-    ok: Boolean(selectedHint?.target),
+    ok,
     machine_id: machine.machine_id,
     requested_machine_id: machineId,
     generated_at: generatedAt,
@@ -7950,7 +8024,7 @@ function resolveMachineRoute(machineId, options = {}) {
     source: route,
     target: selectedHint?.target ?? null,
     command_target: selectedHint?.target ?? null,
-    confidence: routeConfidence({ machine, hint: selectedHint, matchedBy }),
+    confidence,
     local,
     evidence: {
       topology: true,
@@ -7960,6 +8034,15 @@ function resolveMachineRoute(machineId, options = {}) {
       tailscale_online: machine.tailscale.online,
       selected_hint: selectedHint
     },
+    cacheability: cacheability({
+      ok,
+      observedAt: now,
+      now,
+      ttlMs: options.resolverTtlMs,
+      authority: routeAuthority({ machine, selectedHint, matchedBy }),
+      confidence,
+      reasons: selectedHint ? [] : ["route_target_unresolved"]
+    }),
     warnings
   };
 }
@@ -8256,10 +8339,11 @@ function metadataKeysForDiagnostics(metadata) {
   return Object.keys(metadata).filter((key) => !/(secret|token|key|password|credential)/i.test(key)).sort();
 }
 function resolveMachineWorkspace(options) {
+  const now = options.now ?? new Date;
   const topology = options.topology ?? discoverMachineTopology(options);
   const warnings = [...topology.warnings];
   const { machine, matchedBy } = findRouteMachine(topology, options.machineId);
-  const generatedAt = (options.now ?? new Date).toISOString();
+  const generatedAt = now.toISOString();
   const repoName = options.repoName ?? options.projectId;
   const openFilesRepoName = options.openFilesRepoName ?? "open-files";
   if (!machine) {
@@ -8286,6 +8370,15 @@ function resolveMachineWorkspace(options) {
         manifest_declared: null,
         metadata_keys: []
       },
+      cacheability: cacheability({
+        ok: false,
+        observedAt: now,
+        now,
+        ttlMs: options.resolverTtlMs,
+        authority: "unresolved",
+        confidence: "none",
+        reasons: [`machine_not_found:${options.machineId}`]
+      }),
       warnings
     };
     const diagnostics2 = workspaceDiagnostics({
@@ -8317,10 +8410,16 @@ function resolveMachineWorkspace(options) {
     warnings.push(`open_files_root_inferred:${options.projectId}`);
   if (!projectRootPath)
     warnings.push(`project_root_unresolved:${options.projectId}`);
+  const workspacePaths = {
+    workspace_root: { path: workspaceRootPath, source: workspaceRootSource },
+    project_root: { path: projectRootPath, source: projectRootSource },
+    open_files_root: { path: openFilesRootPath, source: openFilesRootSource }
+  };
+  const workspaceOk = Boolean(projectRootPath);
   const resolution = {
     schema_version: MACHINES_CONSUMER_CONTRACT_VERSION,
     package: topology.package,
-    ok: Boolean(projectRootPath),
+    ok: workspaceOk,
     requested_machine_id: options.machineId,
     machine_id: machine.machine_id,
     generated_at: generatedAt,
@@ -8335,11 +8434,7 @@ function resolveMachineWorkspace(options) {
       trust_status: trustStatus(machine),
       auth_status: authStatus(machine)
     },
-    paths: {
-      workspace_root: { path: workspaceRootPath, source: workspaceRootSource },
-      project_root: { path: projectRootPath, source: projectRootSource },
-      open_files_root: { path: openFilesRootPath, source: openFilesRootSource }
-    },
+    paths: workspacePaths,
     diagnostics: [],
     repair_hints: [],
     evidence: {
@@ -8348,6 +8443,15 @@ function resolveMachineWorkspace(options) {
       manifest_declared: machine.manifest_declared,
       metadata_keys: metadataKeysForDiagnostics(metadata)
     },
+    cacheability: cacheability({
+      ok: workspaceOk,
+      observedAt: now,
+      now,
+      ttlMs: options.resolverTtlMs,
+      authority: workspaceAuthority(workspacePaths),
+      confidence: workspaceOk ? "medium" : "none",
+      reasons: projectRootPath ? [] : [`project_root_unresolved:${options.projectId}`]
+    }),
     warnings
   };
   const diagnostics = workspaceDiagnostics({

package/dist/consumer-schema.d.ts

@@ -0,0 +1,21 @@
+import { MACHINES_CONSUMER_SCHEMA_URI, type MachineResolverSnapshot, type MachineRouteResolution, type MachineTopology, type MachineWorkspaceResolution } from "./topology.js";
+import type { MachineCompatibilityReport } from "./compatibility.js";
+export type MachinesConsumerSchemaEnvelope = "contract" | "topology" | "route" | "workspace" | "compatibility" | "resolver_snapshot";
+export interface MachinesConsumerValidationResult {
+    ok: boolean;
+    envelope: MachinesConsumerSchemaEnvelope;
+    schema_id: typeof MACHINES_CONSUMER_SCHEMA_URI;
+    errors: string[];
+}
+export interface MachinesConsumerSchemaBundle {
+    $schema: "https://json-schema.org/draft/2020-12/schema";
+    $id: typeof MACHINES_CONSUMER_SCHEMA_URI;
+    title: string;
+    type: "object";
+    $defs: Record<string, unknown>;
+}
+export declare const MACHINES_CONSUMER_SCHEMA_BUNDLE: MachinesConsumerSchemaBundle;
+export declare function getMachinesConsumerSchemaBundle(): MachinesConsumerSchemaBundle;
+export declare function validateMachinesConsumerEnvelope(envelope: MachinesConsumerSchemaEnvelope, value: unknown): MachinesConsumerValidationResult;
+export type MachinesConsumerEnvelopeValue = MachineTopology | MachineRouteResolution | MachineWorkspaceResolution | MachineCompatibilityReport | MachineResolverSnapshot;
+//# sourceMappingURL=consumer-schema.d.ts.map

package/dist/consumer-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consumer-schema.d.ts","sourceRoot":"","sources":["../src/consumer-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,4BAA4B,EAC5B,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,KAAK,0BAA0B,EAChC,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAErE,MAAM,MAAM,8BAA8B,GACtC,UAAU,GACV,UAAU,GACV,OAAO,GACP,WAAW,GACX,eAAe,GACf,mBAAmB,CAAC;AAExB,MAAM,WAAW,gCAAgC;IAC/C,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,EAAE,8BAA8B,CAAC;IACzC,SAAS,EAAE,OAAO,4BAA4B,CAAC;IAC/C,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,4BAA4B;IAC3C,OAAO,EAAE,8CAA8C,CAAC;IACxD,GAAG,EAAE,OAAO,4BAA4B,CAAC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,eAAO,MAAM,+BAA+B,EAAE,4BAoI7C,CAAC;AAiCF,wBAAgB,+BAA+B,IAAI,4BAA4B,CAE9E;AAED,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,8BAA8B,EACxC,KAAK,EAAE,OAAO,GACb,gCAAgC,CA+ClC;AAED,MAAM,MAAM,6BAA6B,GACrC,eAAe,GACf,sBAAsB,GACtB,0BAA0B,GAC1B,0BAA0B,GAC1B,uBAAuB,CAAC"}

package/dist/consumer.d.ts

@@ -1,5 +1,7 @@
-export { MACHINES_CONSUMER_CAPABILITIES, MACHINES_CONSUMER_CONTRACT, MACHINES_CONSUMER_ENTRYPOINT, MACHINES_CONSUMER_CONTRACT_VERSION, MACHINES_PACKAGE_NAME, discoverMachineTopology, getMachinesConsumerCapabilities, getLocalMachineTopology, resolveMachineRoute, resolveMachineWorkspace, } from "./topology.js";
-export type { MachineRouteConfidence, MachineRouteHint, MachineRouteKind, MachineRouteOptions, MachineRouteResolution, MachineTopology, MachineTopologyEntry, MachineTopologyOptions, MachineWorkspaceAuthStatus, MachineWorkspaceDiagnostic, MachineWorkspaceDiagnosticStatus, MachineWorkspaceOptions, MachineWorkspacePath, MachineWorkspacePathSource, MachineWorkspaceProject, MachineWorkspaceRepairHint, MachineWorkspaceResolution, MachineWorkspaceTrustStatus, MachinesConsumerContract, MachinesConsumerEnvelope, MachinesConsumerCapabilities, MachinesContractPackage, TopologyCommandResult, TopologyCommandRunner, } from "./topology.js";
+export { MACHINES_CONSUMER_CAPABILITIES, MACHINES_CONSUMER_CONTRACT, MACHINES_CONSUMER_ENTRYPOINT, MACHINES_CONSUMER_CONTRACT_VERSION, MACHINES_CONSUMER_FIELD_CAPABILITIES, MACHINES_CONSUMER_SCHEMA_ARTIFACT, MACHINES_CONSUMER_SCHEMA_URI, MACHINES_PACKAGE_NAME, DEFAULT_MACHINE_RESOLVER_TTL_MS, createMachineResolverSnapshot, discoverMachineTopology, getMachinesConsumerCapabilities, getLocalMachineTopology, resolveMachineRoute, resolveMachineWorkspace, } from "./topology.js";
+export type { MachineRouteConfidence, MachineRouteHint, MachineRouteKind, MachineRouteOptions, MachineRouteResolution, MachineResolverAuthority, MachineResolverCacheability, MachineResolverSnapshot, MachineResolverSnapshotRoute, MachineResolverSnapshotWorkspace, MachineTopology, MachineTopologyEntry, MachineTopologyOptions, MachineWorkspaceAuthStatus, MachineWorkspaceDiagnostic, MachineWorkspaceDiagnosticStatus, MachineWorkspaceOptions, MachineWorkspacePath, MachineWorkspacePathSource, MachineWorkspaceProject, MachineWorkspaceRepairHint, MachineWorkspaceResolution, MachineWorkspaceTrustStatus, MachinesConsumerContract, MachinesConsumerEnvelope, MachinesConsumerFieldCapabilities, MachinesConsumerCapabilities, MachinesContractPackage, TopologyCommandResult, TopologyCommandRunner, } from "./topology.js";
+export { MACHINES_CONSUMER_SCHEMA_BUNDLE, getMachinesConsumerSchemaBundle, validateMachinesConsumerEnvelope, } from "./consumer-schema.js";
+export type { MachinesConsumerEnvelopeValue, MachinesConsumerSchemaBundle, MachinesConsumerSchemaEnvelope, MachinesConsumerValidationResult, } from "./consumer-schema.js";
 export { checkMachineCompatibility, } from "./compatibility.js";
 export type { CompatibilityCheck, CompatibilityCommandRunner, CompatibilityCommandSpec, CompatibilityPackageSpec, CompatibilitySource, CompatibilityStatus, CompatibilityWorkspaceSpec, MachineCompatibilityOptions, MachineCompatibilityReport, } from "./compatibility.js";
 export { resolveMachineCommand, runMachineCommand, } from "./remote.js";

package/dist/consumer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"consumer.d.ts","sourceRoot":"","sources":["../src/consumer.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,8BAA8B,EAC9B,0BAA0B,EAC1B,4BAA4B,EAC5B,kCAAkC,EAClC,qBAAqB,EACrB,uBAAuB,EACvB,+BAA+B,EAC/B,uBAAuB,EACvB,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,sBAAsB,EACtB,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACnB,sBAAsB,EACtB,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACtB,0BAA0B,EAC1B,0BAA0B,EAC1B,gCAAgC,EAChC,uBAAuB,EACvB,oBAAoB,EACpB,0BAA0B,EAC1B,uBAAuB,EACvB,0BAA0B,EAC1B,0BAA0B,EAC1B,2BAA2B,EAC3B,wBAAwB,EACxB,wBAAwB,EACxB,4BAA4B,EAC5B,uBAAuB,EACvB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,yBAAyB,GAC1B,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,kBAAkB,EAClB,0BAA0B,EAC1B,wBAAwB,EACxB,wBAAwB,EACxB,mBAAmB,EACnB,mBAAmB,EACnB,0BAA0B,EAC1B,2BAA2B,EAC3B,0BAA0B,GAC3B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,oBAAoB,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,eAAe,EACf,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,iBAAiB,GAClB,MAAM,cAAc,CAAC"}
+{"version":3,"file":"consumer.d.ts","sourceRoot":"","sources":["../src/consumer.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,8BAA8B,EAC9B,0BAA0B,EAC1B,4BAA4B,EAC5B,kCAAkC,EAClC,oCAAoC,EACpC,iCAAiC,EACjC,4BAA4B,EAC5B,qBAAqB,EACrB,+BAA+B,EAC/B,6BAA6B,EAC7B,uBAAuB,EACvB,+BAA+B,EAC/B,uBAAuB,EACvB,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,sBAAsB,EACtB,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACnB,sBAAsB,EACtB,wBAAwB,EACxB,2BAA2B,EAC3B,uBAAuB,EACvB,4BAA4B,EAC5B,gCAAgC,EAChC,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACtB,0BAA0B,EAC1B,0BAA0B,EAC1B,gCAAgC,EAChC,uBAAuB,EACvB,oBAAoB,EACpB,0BAA0B,EAC1B,uBAAuB,EACvB,0BAA0B,EAC1B,0BAA0B,EAC1B,2BAA2B,EAC3B,wBAAwB,EACxB,wBAAwB,EACxB,iCAAiC,EACjC,4BAA4B,EAC5B,uBAAuB,EACvB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,+BAA+B,EAC/B,+BAA+B,EAC/B,gCAAgC,GACjC,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,6BAA6B,EAC7B,4BAA4B,EAC5B,8BAA8B,EAC9B,gCAAgC,GACjC,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,yBAAyB,GAC1B,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,kBAAkB,EAClB,0BAA0B,EAC1B,wBAAwB,EACxB,wBAAwB,EACxB,mBAAmB,EACnB,mBAAmB,EACnB,0BAA0B,EAC1B,2BAA2B,EAC3B,0BAA0B,GAC3B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,oBAAoB,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,eAAe,EACf,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,iBAAiB,GAClB,MAAM,cAAc,CAAC"}