@fairfox/polly 0.77.3 → 0.78.0

package/dist/src/shared/lib/peer-relay-adapter.d.ts

@@ -53,6 +53,11 @@ export interface CreatePeerStateClientOptions {
     sign?: boolean;
     /** Keyring for the signing layer. Required when `sign` is true. */
     keyring?: MeshKeyring;
+    /** Network-adapter factory. Defaults to constructing a real
+     * `WebSocketClientAdapter` against `url`. Injecting a factory lets tests (or
+     * instrumentation) substitute a fake adapter so they stay off the network —
+     * the production path leaves this unset. */
+    adapterFactory?: (url: string, retryInterval?: number) => WebSocketClientAdapter;
 }
 export interface PeerStateClient {
     /** A configured Repo backed by the WebSocket relay. Pass to

package/dist/src/shared/lib/peer-repo-server.d.ts

@@ -88,6 +88,21 @@ export interface PeerRepoServer {
         dryRun?: boolean;
     }) => Promise<SweepResult>;
 }
+/**
+ * Recover every documentId from a NodeFS storage tree.
+ *
+ * automerge-repo's NodeFS adapter shards each document two levels deep —
+ * the first two characters of the documentId, then the remainder — so
+ * the directory structure is itself the document list. A real document
+ * is a directory (holding `snapshot` / `incremental` chunk
+ * subdirectories); flat files such as the storage-adapter-id are
+ * skipped. A missing storage directory (a server that has never
+ * written) yields an empty list.
+ *
+ * Exported for unit testing only — not re-exported from the package's
+ * public entry points.
+ */
+export declare function listNodeFSDocumentIds(baseDirectory: string): Promise<string[]>;
 /**
  * Construct a Polly peer-relay server. Returns a Repo that participates as
  * the always-on peer, the underlying WebSocket server and storage adapter

package/dist/tools/verify/src/cli.js

@@ -249,6 +249,50 @@ var init_expression_validator = __esm(() => {
   WEAK_NEGATION = /([a-zA-Z_][\w.]*(?:\.value\.[\w.]+|\.value\b|))?\s*!==?\s*("[^"]*"|'[^']*'|\d+|true|false|null)/;
 });
 
+// tools/verify/src/analysis/coupled-fields.ts
+var exports_coupled_fields = {};
+__export(exports_coupled_fields, {
+  checkCoupledFields: () => checkCoupledFields
+});
+function norm(field) {
+  return field.replace(/_/g, ".");
+}
+function checkCoupledFields(coupledFields, handlers) {
+  const violations = [];
+  for (const rawGroup of coupledFields) {
+    const group = rawGroup.map(norm);
+    const groupSet = new Set(group);
+    if (groupSet.size < 2)
+      continue;
+    for (const handler of handlers) {
+      const violation = subsetViolation(group, groupSet, handler);
+      if (violation)
+        violations.push(violation);
+    }
+  }
+  return { valid: violations.length === 0, violations };
+}
+function writtenFields(group, handler) {
+  const written = new Set;
+  for (const assignment of handler.assignments) {
+    const field = norm(assignment.field);
+    if (group.has(field))
+      written.add(field);
+  }
+  return written;
+}
+function subsetViolation(group, groupSet, handler) {
+  const written = writtenFields(groupSet, handler);
+  if (written.size === 0 || written.size === groupSet.size)
+    return null;
+  return {
+    group,
+    handler: handler.messageType,
+    written: group.filter((f) => written.has(f)),
+    missing: group.filter((f) => !written.has(f))
+  };
+}
+
 // tools/verify/src/analysis/non-interference.ts
 var exports_non_interference = {};
 __export(exports_non_interference, {
@@ -2678,6 +2722,9 @@ var init_tla = __esm(() => {
       this.indent--;
       this.indent--;
       this.line("");
+      if (config.capabilities && config.capabilities.length > 0) {
+        this.addCapabilityInvariants(config.capabilities);
+      }
       if (this.extractedInvariants.length > 0) {
         this.line("\\* Extracted invariants from code annotations");
         this.line("");
@@ -2694,6 +2741,15 @@ var init_tla = __esm(() => {
       this.line("\\* State constraint to bound state space");
       this.addStateConstraint(config, _analysis);
     }
+    addCapabilityInvariants(capabilities) {
+      for (const cap of capabilities) {
+        this.extractedInvariants.push({
+          name: `Capability_${cap.name}`,
+          description: cap.message ? `polly#160 capability: ${cap.message}` : `polly#160 capability: ${cap.name} requires its precondition`,
+          expression: `(!(${cap.enabledBy})) || (${cap.requires})`
+        });
+      }
+    }
     addTemporalConstraints(constraints) {
       this.line("\\* Tier 2: Temporal constraint invariants");
       this.line("\\* Enforce ordering requirements between message types");
@@ -3910,6 +3966,85 @@ function generateConfig(analysis, projectType = "chrome-extension") {
 // tools/verify/src/config/parser.ts
 import * as fs from "node:fs";
 import * as path from "node:path";
+
+// tools/verify/src/config/capability-validation.ts
+init_expression_validator();
+function validateCapabilities(capabilities, stateConfig) {
+  if (!capabilities || capabilities.length === 0)
+    return [];
+  const issues = [];
+  const configKeys = new Set(Object.keys(stateConfig));
+  for (const cap of capabilities) {
+    const name = cap.name?.trim();
+    if (!name) {
+      issues.push({
+        type: "invalid_value",
+        severity: "error",
+        field: "capabilities",
+        message: "Capability is missing a name.",
+        suggestion: "Give each capability a unique name; it becomes the TLA+ invariant identifier."
+      });
+      continue;
+    }
+    issues.push(...validateExpression(name, "enabledBy", cap.enabledBy, configKeys, stateConfig), ...validateExpression(name, "requires", cap.requires, configKeys, stateConfig));
+  }
+  return issues;
+}
+function validateExpression(name, slot, expr, configKeys, stateConfig) {
+  const field = `capabilities.${name}.${slot}`;
+  if (!expr?.trim()) {
+    return [
+      {
+        type: "capability_empty_expression",
+        severity: "error",
+        field,
+        message: `Capability "${name}" has an empty ${slot} expression.`,
+        suggestion: `Provide a state expression for ${slot}, e.g. "state.authenticated".`
+      }
+    ];
+  }
+  const refs = extractFieldRefs(expr);
+  if (refs.length === 0) {
+    return [
+      {
+        type: "capability_empty_expression",
+        severity: "error",
+        field,
+        message: `Capability "${name}" ${slot} expression "${expr}" references no state field.`,
+        suggestion: 'Reference state via the state./.value form (e.g. "state.authReady"); a bare identifier produces a silently-vacuous invariant.'
+      }
+    ];
+  }
+  return refs.filter((ref) => !fieldInConfig(ref, configKeys, stateConfig)).map((ref) => ({
+    type: "capability_unknown_field",
+    severity: "error",
+    field,
+    message: `Capability "${name}" ${slot} references "${ref}", which is not in the state config.`,
+    suggestion: `Add "${ref}" to state, or correct the expression. Known fields: ${[...configKeys].join(", ")}`
+  }));
+}
+function validateCoupledFields(coupledFields, stateConfig) {
+  if (!coupledFields || coupledFields.length === 0)
+    return [];
+  const issues = [];
+  const configKeys = new Set(Object.keys(stateConfig));
+  coupledFields.forEach((group, i) => {
+    for (const field of group) {
+      if (!fieldInConfig(field, configKeys, stateConfig)) {
+        issues.push({
+          type: "coupled_unknown_field",
+          severity: "error",
+          field: `coupledFields[${i}]`,
+          message: `Coupled field "${field}" is not in the state config.`,
+          suggestion: `Use a declared state field. Known fields: ${[...configKeys].join(", ")}`
+        });
+      }
+    }
+  });
+  return issues;
+}
+
+// tools/verify/src/config/parser.ts
 class ConfigValidator {
   issues = [];
   validate(configPath) {
@@ -4032,6 +4167,8 @@ class ConfigValidator {
     if (config.subsystems) {
       this.validateSubsystems(config.subsystems, config.state, config.messages);
     }
+    this.issues.push(...validateCapabilities(config.capabilities, config.state));
+    this.issues.push(...validateCoupledFields(config.coupledFields, config.state));
   }
   findNullPlaceholders(obj, path2) {
     if (obj === null || obj === undefined) {
@@ -7941,6 +8078,28 @@ function getMaxDepth(config) {
   }
   return;
 }
+async function runCoupledFieldsLint(config, analysis) {
+  const groups = config.coupledFields ?? [];
+  if (groups.length === 0)
+    return;
+  const { checkCoupledFields: checkCoupledFields2 } = await Promise.resolve().then(() => exports_coupled_fields);
+  const result = checkCoupledFields2(groups, analysis.handlers);
+  if (result.valid) {
+    console.log(color("✓ Coupled fields: verified (no partial-subset writes)", COLORS.green));
+    console.log();
+    return;
+  }
+  console.log(color(`⚠️  Coupled-field violations detected:
+`, COLORS.yellow));
+  for (const v of result.violations) {
+    console.log(color(`   • Handler "${v.handler}" writes {${v.written.join(", ")}} but not {${v.missing.join(", ")}} of coupled group {${v.group.join(", ")}}`, COLORS.yellow));
+  }
+  console.log();
+  console.log(color("   These fields are declared to move together; a capability granted without its", COLORS.yellow));
+  console.log(color("   precondition is a likely cause. Co-write the full group in each handler, or model", COLORS.yellow));
+  console.log(color("   the relationship with a `capabilities` invariant.", COLORS.yellow));
+  console.log();
+}
 async function runFullVerification(configPath) {
   const config = await loadVerificationConfig(configPath);
   const analysis = await runCodebaseAnalysis();
@@ -7953,6 +8112,7 @@ async function runFullVerification(configPath) {
   }
   const declaredMeshDocs = new Set(Object.keys(typedConfig.mesh ?? {}));
   displayMeshOrPeerSignalWarnings(typedAnalysis, declaredMeshDocs);
+  await runCoupledFieldsLint(typedConfig, typedAnalysis);
   if (typedConfig.subsystems && Object.keys(typedConfig.subsystems).length > 0) {
     await runSubsystemVerification(typedConfig, typedAnalysis);
     return;
@@ -8393,4 +8553,4 @@ main().catch((error) => {
   process.exit(1);
 });
 
-//# debugId=A59978709BAED66964756E2164756E21
+//# debugId=43F6AECD3B4E1E6264756E2164756E21