@smthrs/std 0.0.0-stage → 1.0.0-rc.3

package/dist/cjs/TestRun.js

@@ -0,0 +1,228 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name2 in all)
+    __defProp(target, name2, { get: all[name2], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var TestRun_exports = {};
+__export(TestRun_exports, {
+  DEFAULT_TIMEOUT_MS: () => DEFAULT_TIMEOUT_MS,
+  Input: () => Input,
+  MAX_CAPTURE_BYTES: () => MAX_CAPTURE_BYTES,
+  Outcome: () => Outcome,
+  Output: () => Output,
+  activity: () => activity,
+  capabilities: () => capabilities,
+  description: () => description,
+  effects: () => effects,
+  effectsFor: () => effectsFor,
+  flow: () => flow,
+  name: () => name,
+  presentation: () => presentation,
+  run: () => run,
+  scratchDirectory: () => scratchDirectory
+});
+module.exports = __toCommonJS(TestRun_exports);
+var Effect = __toESM(require("effect/Effect"), 1);
+var Option = __toESM(require("effect/Option"), 1);
+var Schema = __toESM(require("effect/Schema"), 1);
+var Container = __toESM(require("./Container.js"), 1);
+var import_Declaration = require("./internal/Declaration.js");
+var Exec = __toESM(require("./internal/Exec.js"), 1);
+var import_GitWorktree = require("./internal/GitWorktree.js");
+var Prune = __toESM(require("./internal/Prune.js"), 1);
+var TestReport = __toESM(require("./internal/TestReport.js"), 1);
+var import_Text = require("./internal/Text.js");
+var Probe = __toESM(require("./Probe.js"), 1);
+var StdError = __toESM(require("./StdError.js"), 1);
+var TestRunner = __toESM(require("./TestRunner.js"), 1);
+const name = "test";
+const description = "Run this repository's declared test runner and get {passed, failed[ids]}, not raw output. against:'base' also runs it on the pristine base commit, so a pre-existing failure is named, not investigated.";
+const scratchDirectory = Prune.testBaseScratch;
+const DEFAULT_TIMEOUT_MS = 6e5;
+const MAX_CAPTURE_BYTES = 8e6;
+const Input = Schema.Struct({
+  selection: Schema.optional(Schema.Array(Schema.String)).annotate({
+    description: "Test ids, paths or selectors passed to the runner as arguments; all tests when omitted"
+  }),
+  against: Schema.optional(Schema.Literals(["workspace", "base"])).annotate({
+    description: "workspace (default) runs the tree as it stands; base also runs the pristine base commit and reports which failures are new"
+  }),
+  timeoutMs: Schema.optional(Schema.Number).annotate({ description: "Wall-clock timeout in milliseconds" })
+});
+const Outcome = Schema.Struct({
+  command: Schema.String.annotate({
+    description: "The logical invocation that ran, without container transport arguments"
+  }),
+  exitCode: Schema.Number,
+  passed: Schema.Number.annotate({ description: "Tests reported passing; 0 when parsed is false" }),
+  failed: Schema.Array(Schema.String).annotate({ description: "Ids of the tests reported failing or erroring" }),
+  parsed: Schema.Boolean.annotate({
+    description: "Whether the runner's complete report could be read; when false, tail is all there is. Base attribution is omitted unless both reports are complete"
+  }),
+  tail: Schema.String.annotate({ description: "The end of the runner's combined output" }),
+  // `<field>Truncated` beside `<field>` is the wire convention
+  // `@smthrs/harness/TruncatedOutput` reads to refuse a later write of these
+  // exact bytes. A tail written over a file replaces it with its own end.
+  tailTruncated: Schema.Boolean.annotate({
+    description: "Whether the runner printed more than tail carries, leaving tail a fragment that must not be written"
+  }),
+  tailDroppedBytes: Schema.Number.annotate({ description: "UTF-8 bytes omitted from the start of tail" }),
+  invalidProbe: Schema.optional(Probe.InvalidProbe)
+});
+const Output = Schema.Struct({
+  ...Outcome.fields,
+  base: Schema.optional(Schema.Struct({
+    ...Outcome.fields,
+    ref: Schema.String.annotate({ description: "The ref the baseline tree came from" }),
+    commit: Schema.String.annotate({ description: "The commit the baseline tree came from" })
+  })),
+  introduced: Schema.optional(Schema.Array(Schema.String)).annotate({
+    description: "Failing here and not on the base tree: the failures this working tree is responsible for"
+  }),
+  preexisting: Schema.optional(Schema.Array(Schema.String)).annotate({
+    description: "Failing on both trees: not yours, and not worth investigating"
+  }),
+  fixed: Schema.optional(Schema.Array(Schema.String)).annotate({
+    description: "Failing on the base tree and passing here"
+  })
+});
+const effects = (0, import_Declaration.envelope)({ tier: "irreversible", mode: "expected", reads: [], writes: [] });
+const effectsFor = (_input) => effects;
+const capabilities = [(0, import_Declaration.capability)("proc:spawn", "*")];
+const flow = { name, description, input: Input, output: Output, capabilities, effects };
+const activity = "tests";
+const presentation = {
+  verb: { pending: "running", success: "ran", failure: "failed to run" },
+  subject: "selection",
+  result: "tests"
+};
+const invocation = (runner, selection) => ({
+  file: "bash",
+  args: ["-c", `${runner.command} "$@"`, runner.command, ...selection]
+});
+const failed = (message, code = "command_failed") => new StdError.StdError({ code, message });
+const execute = (runner, transport, options) => Effect.gen(function* () {
+  const plan = invocation(runner, options.selection);
+  const routed = runner.container === void 0 ? { ...plan, env: runner.env } : Option.isNone(transport) ? yield* Effect.fail(Container.unavailable(runner.container)) : yield* transport.value.exec({
+    container: runner.container,
+    file: plan.file,
+    args: plan.args,
+    ...options.cwd === void 0 ? {} : { cwd: options.cwd },
+    ...runner.env === void 0 ? {} : { env: runner.env },
+    stdin: false
+  });
+  const quoted = [plan.file, ...plan.args].join(" ");
+  const result = yield* Exec.exec(routed.file, {
+    args: [...routed.args],
+    ...options.cwd === void 0 || runner.container !== void 0 ? {} : { cwd: options.cwd },
+    ...routed.env === void 0 ? {} : { env: routed.env },
+    timeoutMs: options.timeoutMs,
+    maxCaptureBytes: MAX_CAPTURE_BYTES
+  }).pipe(
+    Effect.mapError(
+      (error) => new StdError.StdError({
+        code: Exec.toStdErrorCode(error),
+        message: `The test runner did not run: ${error.message}`,
+        ...error.limitMillis === void 0 ? {} : { limitMillis: error.limitMillis }
+      })
+    )
+  );
+  const combined = result.stderr === "" ? result.stdout : result.stdout === "" ? result.stderr : `${result.stdout}
+${result.stderr}`;
+  const tail = (0, import_Text.truncateBytes)(combined, import_Text.MAX_SHELL_OUTPUT_BYTES, { keep: "tail" });
+  const report = TestReport.parse(combined);
+  const probe = yield* Probe.classify({
+    command: quoted,
+    exitCode: result.exitCode,
+    output: tail.text
+  }).pipe(Effect.mapError(Probe.unjudged));
+  const capturedDroppedBytes = result.stdoutDroppedBytes + result.stderrDroppedBytes;
+  return {
+    outcome: {
+      command: quoted,
+      exitCode: result.exitCode,
+      passed: report.passed,
+      failed: report.failed,
+      parsed: report.parsed,
+      tail: tail.text,
+      tailTruncated: capturedDroppedBytes > 0 || tail.truncated,
+      tailDroppedBytes: capturedDroppedBytes + tail.droppedBytes,
+      ...probe.invalidProbe === void 0 ? {} : { invalidProbe: probe.invalidProbe }
+    },
+    report
+  };
+});
+const run = Effect.fn("TestRun.run")(function* (input) {
+  const declaration = yield* TestRunner.TestRunner;
+  const runner = yield* declaration.declared;
+  if (input.against === "base" && runner.baseline === false) {
+    return yield* Effect.fail(failed(
+      "Baseline comparison is unavailable on this host. Run against the workspace.",
+      "provider_unavailable"
+    ));
+  }
+  const transport = yield* Effect.serviceOption(Container.Container);
+  const selection = input.selection ?? [];
+  const timeoutMs = input.timeoutMs ?? runner.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const current = yield* execute(runner, transport, {
+    selection,
+    cwd: runner.cwd,
+    timeoutMs
+  });
+  if (input.against !== "base") return current.outcome;
+  const root = runner.root ?? runner.cwd;
+  if (root === void 0) {
+    return yield* Effect.fail(
+      failed(
+        "The declared runner names no repository directory, so there is no base tree to check out",
+        "invalid_input"
+      )
+    );
+  }
+  const base = yield* import_GitWorktree.GitWorktree.resolveCommit(
+    root,
+    runner.baseRef === void 0 ? [TestRunner.captureBase, "HEAD"] : [runner.baseRef]
+  ).pipe(Effect.mapError(
+    (error) => error.code === "not_found" ? failed(`No pristine base to compare against: ${error.message} Run against the workspace instead.`, "not_found") : error
+  ));
+  const baseline = yield* import_GitWorktree.GitWorktree.withDetachedWorktree(
+    root,
+    `${scratchDirectory}/run`,
+    base.commit,
+    (scratch) => execute(runner, transport, {
+      selection,
+      cwd: runner.cwd === void 0 ? scratch : `${runner.cwd.replace(/\/+$/, "")}${scratch.slice(root.replace(/\/+$/, "").length)}`,
+      timeoutMs
+    })
+  );
+  const difference = TestReport.attribute(current.report, baseline.report);
+  return {
+    ...current.outcome,
+    base: { ...baseline.outcome, ref: base.ref, commit: base.commit },
+    ...difference === void 0 ? {} : difference
+  };
+});
+//# sourceMappingURL=TestRun.js.map

package/dist/cjs/TestRun.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/TestRun.ts"],
+  "sourcesContent": ["/**\n * The `test` flow: run the declared suite, and answer with the two facts.\n *\n * Two things this returns that a shell command cannot. First, a *reading*:\n * `{passed, failed}` parsed from the runner's own report, with the raw tail\n * kept for whatever the parse could not carry \u2014 a suite's answer is a number\n * and a list of names, not twenty kilobytes of stdout for a model to re-read.\n *\n * Second, `against: \"base\"`: the same selection also runs against the pristine\n * base commit in a scratch checkout, and the two failure sets are differenced\n * here. That is the whole of attribution, in one call. Without it, agents pay\n * for it in frames \u2014 sphinx-8721 spent fourteen frames because a pre-existing\n * failure was never baselined, sympy-13878 spent $0.90 on the same mistake, and\n * django-24970 spent three frames. The rule the harness teaches (\"before\n * blaming your own edit, run the same command on the unmodified tree\") is only\n * cheap when the tool can do it.\n *\n * A third thing is answered on the way out: whether a non-zero exit is the\n * tree's failure at all, or the command failing to resolve a name. Jev decides\n * it through `Probe.classify`, so the flow needs an `Evaluator` and a host\n * uses its configured subscription seat. A judge that does not answer fails the call with\n * the code `Probe.unjudged` names, because a run nobody judged is not a run\n * this flow can report on.\n *\n * @since 1.0.0\n */\n\nimport type * as ChildProcessSpawner from \"@smthrs/kernel/ChildProcessSpawner\"\nimport type * as Evaluator from \"@smthrs/model/Evaluator\"\nimport * as Effect from \"effect/Effect\"\nimport * as Option from \"effect/Option\"\nimport * as Schema from \"effect/Schema\"\nimport * as Container from \"./Container.ts\"\nimport { capability, envelope } from \"./internal/Declaration.ts\"\nimport * as Exec from \"./internal/Exec.ts\"\nimport { GitWorktree } from \"./internal/GitWorktree.ts\"\nimport * as Prune from \"./internal/Prune.ts\"\nimport * as TestReport from \"./internal/TestReport.ts\"\nimport { MAX_SHELL_OUTPUT_BYTES, truncateBytes } from \"./internal/Text.ts\"\nimport * as Probe from \"./Probe.ts\"\nimport * as StdError from \"./StdError.ts\"\nimport * as TestRunner from \"./TestRunner.ts\"\n\n/**\n * Registry name for the test flow.\n *\n * @category identifiers\n * @since 1.0.0\n */\nexport const name = \"test\"\n\n/**\n * Model-facing description of the test flow.\n *\n * @category descriptions\n * @since 1.0.0\n */\nexport const description =\n  \"Run this repository's declared test runner and get {passed, failed[ids]}, not raw output. against:'base' also runs it on the pristine base commit, so a pre-existing failure is named, not investigated.\"\n\n/**\n * The parent directory baseline checkouts are written into, relative to the\n * repository root, and therefore also relative to the runner's own directory.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const scratchDirectory = Prune.testBaseScratch\n\n/**\n * Default wall-clock budget for one test run.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const DEFAULT_TIMEOUT_MS = 600_000\n\n/**\n * Maximum bytes retained from each stream while a test run executes.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const MAX_CAPTURE_BYTES = 8_000_000\n\n/**\n * Input schema for the test flow.\n *\n * @category schemas\n * @since 1.0.0\n */\nexport const Input = Schema.Struct({\n  selection: Schema.optional(Schema.Array(Schema.String)).annotate({\n    description: \"Test ids, paths or selectors passed to the runner as arguments; all tests when omitted\"\n  }),\n  against: Schema.optional(Schema.Literals([\"workspace\", \"base\"])).annotate({\n    description:\n      \"workspace (default) runs the tree as it stands; base also runs the pristine base commit and reports which failures are new\"\n  }),\n  timeoutMs: Schema.optional(Schema.Number).annotate({ description: \"Wall-clock timeout in milliseconds\" })\n})\n\n/**\n * Decoded input accepted by the `test` flow.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Input = typeof Input.Type\n\n/**\n * One run's outcome.\n *\n * @category schemas\n * @since 1.0.0\n */\nexport const Outcome = Schema.Struct({\n  command: Schema.String.annotate({\n    description: \"The logical invocation that ran, without container transport arguments\"\n  }),\n  exitCode: Schema.Number,\n  passed: Schema.Number.annotate({ description: \"Tests reported passing; 0 when parsed is false\" }),\n  failed: Schema.Array(Schema.String).annotate({ description: \"Ids of the tests reported failing or erroring\" }),\n  parsed: Schema.Boolean.annotate({\n    description:\n      \"Whether the runner's complete report could be read; when false, tail is all there is. Base attribution is omitted unless both reports are complete\"\n  }),\n  tail: Schema.String.annotate({ description: \"The end of the runner's combined output\" }),\n  // `<field>Truncated` beside `<field>` is the wire convention\n  // `@smthrs/harness/TruncatedOutput` reads to refuse a later write of these\n  // exact bytes. A tail written over a file replaces it with its own end.\n  tailTruncated: Schema.Boolean.annotate({\n    description: \"Whether the runner printed more than tail carries, leaving tail a fragment that must not be written\"\n  }),\n  tailDroppedBytes: Schema.Number.annotate({ description: \"UTF-8 bytes omitted from the start of tail\" }),\n  invalidProbe: Schema.optional(Probe.InvalidProbe)\n})\n\n/**\n * Output schema for the test flow.\n *\n * @category schemas\n * @since 1.0.0\n */\nexport const Output = Schema.Struct({\n  ...Outcome.fields,\n  base: Schema.optional(Schema.Struct({\n    ...Outcome.fields,\n    ref: Schema.String.annotate({ description: \"The ref the baseline tree came from\" }),\n    commit: Schema.String.annotate({ description: \"The commit the baseline tree came from\" })\n  })),\n  introduced: Schema.optional(Schema.Array(Schema.String)).annotate({\n    description: \"Failing here and not on the base tree: the failures this working tree is responsible for\"\n  }),\n  preexisting: Schema.optional(Schema.Array(Schema.String)).annotate({\n    description: \"Failing on both trees: not yours, and not worth investigating\"\n  }),\n  fixed: Schema.optional(Schema.Array(Schema.String)).annotate({\n    description: \"Failing on the base tree and passing here\"\n  })\n})\n\n/**\n * Decoded output returned by the `test` flow.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Output = typeof Output.Type\n\n/**\n * Static conservative effect envelope for the test flow.\n *\n * @category effects\n * @since 1.0.0\n */\nexport const effects = envelope({ tier: \"irreversible\", mode: \"expected\", reads: [], writes: [] })\n\n/**\n * Narrows the effect envelope for a decoded invocation.\n *\n * @category effects\n * @since 1.0.0\n */\nexport const effectsFor = (_input: typeof Input.Type) => effects\n\n/**\n * Capabilities required by the test flow.\n *\n * @category capabilities\n * @since 1.0.0\n */\nexport const capabilities = [capability(\"proc:spawn\", \"*\")]\n\n/**\n * Declaration-only test flow.\n *\n * @category flows\n * @since 1.0.0\n */\nexport const flow = { name, description, input: Input, output: Output, capabilities, effects } as const\n\n/**\n * What a call to this flow does, for a reader of a run.\n *\n * Display metadata only. `@smthrs/registry` `Descriptor.FlowActivity` is the\n * governing vocabulary and `StandardFlows` binds this value onto the flow's\n * descriptor, where the binding site checks it. `declarationDigest` excludes\n * it, so declaring it cannot invalidate a call identity or a cached prompt.\n *\n * @category presentation\n * @since 1.0.0-rc.0\n */\nexport const activity = \"tests\" as const\n\n/**\n * How one recorded call to this flow reads: the verb for each settlement, the\n * input field that is its subject, and the measured output fields a one-line\n * summary may count.\n *\n * Display metadata only, governed by `@smthrs/registry`\n * `Descriptor.CallPresentation` and checked where `StandardFlows` binds it.\n *\n * @category presentation\n * @since 1.0.0-rc.0\n */\nexport const presentation = {\n  verb: { pending: \"running\", success: \"ran\", failure: \"failed to run\" },\n  subject: \"selection\",\n  result: \"tests\"\n} as const\n\n/**\n * The invocation for one run: the declared command line with the selection\n * appended as arguments rather than as text.\n *\n * `bash -c '<command> \"$@\"' <command> id\u2026` is how a selection reaches a runner\n * without being quoted into it. A test id holds `::`, `[`, `]`, spaces and\n * shell metacharacters routinely, and every one of them is data here.\n */\nconst invocation = (\n  runner: TestRunner.Runner,\n  selection: ReadonlyArray<string>\n): { readonly file: string; readonly args: ReadonlyArray<string> } => ({\n  file: \"bash\",\n  args: [\"-c\", `${runner.command} \"$@\"`, runner.command, ...selection]\n})\n\nconst failed = (message: string, code: StdError.Code = \"command_failed\"): StdError.StdError =>\n  new StdError.StdError({ code, message })\n\n/** Runs one invocation, in the container when the declaration names one. */\nconst execute = (\n  runner: TestRunner.Runner,\n  transport: Option.Option<Container.Container>,\n  options: {\n    readonly selection: ReadonlyArray<string>\n    readonly cwd: string | undefined\n    readonly timeoutMs: number\n  }\n): Effect.Effect<\n  { readonly outcome: typeof Outcome.Type; readonly report: TestReport.Report },\n  StdError.StdError,\n  ChildProcessSpawner.ChildProcessSpawner | Evaluator.Evaluator\n> =>\n  Effect.gen(function*() {\n    const plan = invocation(runner, options.selection)\n    const routed: Container.Plan = runner.container === undefined ?\n      { ...plan, env: runner.env } :\n      Option.isNone(transport)\n      ? yield* Effect.fail(Container.unavailable(runner.container))\n      : yield* transport.value.exec({\n        container: runner.container,\n        file: plan.file,\n        args: plan.args,\n        ...(options.cwd === undefined ? {} : { cwd: options.cwd }),\n        ...(runner.env === undefined ? {} : { env: runner.env }),\n        stdin: false\n      })\n    // Report the logical invocation, never the transport or its credentials.\n    const quoted = [plan.file, ...plan.args].join(\" \")\n    const result = yield* Exec.exec(routed.file, {\n      args: [...routed.args],\n      ...(options.cwd === undefined || runner.container !== undefined ? {} : { cwd: options.cwd }),\n      ...(routed.env === undefined ? {} : { env: routed.env }),\n      timeoutMs: options.timeoutMs,\n      maxCaptureBytes: MAX_CAPTURE_BYTES\n    }).pipe(\n      Effect.mapError((error) =>\n        new StdError.StdError({\n          code: Exec.toStdErrorCode(error),\n          message: `The test runner did not run: ${error.message}`,\n          ...(error.limitMillis === undefined ? {} : { limitMillis: error.limitMillis })\n        })\n      )\n    )\n    const combined = result.stderr === \"\"\n      ? result.stdout\n      : result.stdout === \"\"\n      ? result.stderr\n      : `${result.stdout}\\n${result.stderr}`\n    const tail = truncateBytes(combined, MAX_SHELL_OUTPUT_BYTES, { keep: \"tail\" })\n    const report = TestReport.parse(combined)\n    // Judged on the text this call returns rather than the text it captured,\n    // so the attribution is made from the output the reader can see. A judge\n    // that does not answer fails the call: see `Probe.unjudged`.\n    const probe = yield* Probe.classify({\n      command: quoted,\n      exitCode: result.exitCode,\n      output: tail.text\n    }).pipe(Effect.mapError(Probe.unjudged))\n    const capturedDroppedBytes = result.stdoutDroppedBytes + result.stderrDroppedBytes\n    return {\n      outcome: {\n        command: quoted,\n        exitCode: result.exitCode,\n        passed: report.passed,\n        failed: report.failed,\n        parsed: report.parsed,\n        tail: tail.text,\n        tailTruncated: capturedDroppedBytes > 0 || tail.truncated,\n        tailDroppedBytes: capturedDroppedBytes + tail.droppedBytes,\n        ...(probe.invalidProbe === undefined ? {} : { invalidProbe: probe.invalidProbe })\n      },\n      report\n    }\n  })\n\n/**\n * Runs the declared suite, and on request the same suite on the pristine base.\n *\n * Baseline Git and both runners use the caller-provided process service.\n * A host that cannot safely stage the base declares `baseline: false`, which\n * refuses the request before running either suite or Git. Library hosts that\n * support staging remove the detached checkout when the call ends.\n *\n * @category handlers\n * @since 1.0.0\n */\nexport const run = Effect.fn(\"TestRun.run\")(function*(\n  input: typeof Input.Type\n): Effect.fn.Return<\n  typeof Output.Type,\n  StdError.StdError,\n  ChildProcessSpawner.ChildProcessSpawner | Evaluator.Evaluator | TestRunner.TestRunner\n> {\n  const declaration = yield* TestRunner.TestRunner\n  const runner = yield* declaration.declared\n  if (input.against === \"base\" && runner.baseline === false) {\n    return yield* Effect.fail(failed(\n      \"Baseline comparison is unavailable on this host. Run against the workspace.\",\n      \"provider_unavailable\"\n    ))\n  }\n  const transport = yield* Effect.serviceOption(Container.Container)\n  const selection = input.selection ?? []\n  const timeoutMs = input.timeoutMs ?? runner.timeoutMs ?? DEFAULT_TIMEOUT_MS\n  const current = yield* execute(runner, transport, {\n    selection,\n    cwd: runner.cwd,\n    timeoutMs\n  })\n  if (input.against !== \"base\") return current.outcome\n\n  const root = runner.root ?? runner.cwd\n  if (root === undefined) {\n    return yield* Effect.fail(\n      failed(\n        \"The declared runner names no repository directory, so there is no base tree to check out\",\n        \"invalid_input\"\n      )\n    )\n  }\n  const base = yield* GitWorktree.resolveCommit(\n    root,\n    runner.baseRef === undefined ? [TestRunner.captureBase, \"HEAD\"] : [runner.baseRef]\n  ).pipe(Effect.mapError((error) =>\n    error.code === \"not_found\"\n      ? failed(`No pristine base to compare against: ${error.message} Run against the workspace instead.`, \"not_found\")\n      : error\n  ))\n  const baseline = yield* GitWorktree.withDetachedWorktree(\n    root,\n    `${scratchDirectory}/run`,\n    base.commit,\n    (scratch) =>\n      execute(runner, transport, {\n        selection,\n        cwd: runner.cwd === undefined\n          ? scratch\n          : `${runner.cwd.replace(/\\/+$/, \"\")}${scratch.slice(root.replace(/\\/+$/, \"\").length)}`,\n        timeoutMs\n      })\n  )\n  const difference = TestReport.attribute(current.report, baseline.report)\n  return {\n    ...current.outcome,\n    base: { ...baseline.outcome, ref: base.ref, commit: base.commit },\n    ...(difference === undefined ? {} : difference)\n  }\n})\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/cjs/TestRunner.d.ts

@@ -0,0 +1,102 @@
+/**
+ * The repository's own test invocation, declared once by the host.
+ *
+ * Every repository already knows how to run its tests, and the harness is told
+ * so at setup. What the measured program shows is what happens when that fact
+ * is not a *callable* thing: agents guess labels
+ * (`management_commands.test_flush`, `tests/related_lookup`, `test_axis.py` —
+ * none of which exist), and a guessed label costs a frame each time. Seven such
+ * invocations are documented across the 45 instances.
+ *
+ * So the invocation is a declaration, not a parameter: a caller of the `test`
+ * flow selects *which* tests, never *how* to run them.
+ *
+ * @since 1.0.0
+ */
+import { Context, Effect, Layer } from "effect";
+import * as StdError from "./StdError.ts";
+/**
+ * The default ref naming a tree as it stood before the agent touched it.
+ *
+ * The engine records the pristine checkout under this ref, so a baseline run
+ * reuses what already exists instead of inventing a second notion of "base".
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export declare const captureBase = "refs/flows/capture-base";
+/**
+ * How this repository runs its tests.
+ *
+ * `cwd` is where the runner runs, and `root` is the host directory holding the
+ * git repository. They differ exactly when the runner runs in a container: the
+ * container sees the repository at `cwd`, the host sees it at `root`, and a
+ * baseline checkout created at `<root>/<name>` is visible to the runner at
+ * `<cwd>/<name>` because it is the same directory under two names.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Runner {
+    /** The runner command line, without any test selection. */
+    readonly command: string;
+    /** Where the runner runs; the container's path when `container` is set. */
+    readonly cwd?: string | undefined;
+    /** The host path of the repository, when it differs from `cwd`. */
+    readonly root?: string | undefined;
+    /** A container to route the run through, via the `Container` transport. */
+    readonly container?: string | undefined;
+    /** Environment the runner needs. */
+    readonly env?: Record<string, string> | undefined;
+    /** The ref whose commit is the pristine base; defaults to {@link captureBase}, then HEAD. */
+    readonly baseRef?: string | undefined;
+    /** False refuses baseline requests before any process runs. */
+    readonly baseline?: false | undefined;
+    /** Default wall-clock budget for one run. */
+    readonly timeoutMs?: number | undefined;
+}
+/**
+ * The declaration service.
+ *
+ * @category services
+ * @since 1.0.0
+ */
+export interface TestRunner {
+    readonly declared: Effect.Effect<Runner, StdError.StdError>;
+}
+/**
+ * The {@link TestRunner} service tag.
+ *
+ * @category services
+ * @since 1.0.0
+ */
+export declare const TestRunner: Context.Service<TestRunner, TestRunner>;
+/**
+ * Declares one repository's runner.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const make: (runner: Runner) => TestRunner;
+/**
+ * Declares that this host knows of no runner.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const makeNoop: () => TestRunner;
+/**
+ * Provides {@link make}.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export declare const layer: (runner: Runner) => Layer.Layer<TestRunner>;
+/**
+ * Provides {@link makeNoop}.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export declare const layerNoop: Layer.Layer<TestRunner>;
+//# sourceMappingURL=TestRunner.d.ts.map

package/dist/cjs/TestRunner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TestRunner.d.ts","sourceRoot":"","sources":["../../src/TestRunner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAA;AAC/C,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAEzC;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,4BAA4B,CAAA;AAEpD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,MAAM;IACrB,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,mEAAmE;IACnE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,oCAAoC;IACpC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAA;IACjD,6FAA6F;IAC7F,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,GAAG,SAAS,CAAA;IACrC,6CAA6C;IAC7C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACxC;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAA;CAC5D;AAED;;;;;GAKG;AACH,eAAO,MAAM,UAAU,EAAE,OAAO,CAAC,OAAO,CAAC,UAAU,EAAE,UAAU,CAA6C,CAAA;AAE5G;;;;;GAKG;AACH,eAAO,MAAM,IAAI,GAAI,QAAQ,MAAM,KAAG,UAAiE,CAAA;AAEvG;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,QAAO,UASxB,CAAA;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,KAAK,GAAI,QAAQ,MAAM,KAAG,KAAK,CAAC,KAAK,CAAC,UAAU,CAA4C,CAAA;AAEzG;;;;;GAKG;AACH,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,UAAU,CAAyC,CAAA"}

package/dist/cjs/TestRunner.js

@@ -0,0 +1,54 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var TestRunner_exports = {};
+__export(TestRunner_exports, {
+  TestRunner: () => TestRunner,
+  captureBase: () => captureBase,
+  layer: () => layer,
+  layerNoop: () => layerNoop,
+  make: () => make,
+  makeNoop: () => makeNoop
+});
+module.exports = __toCommonJS(TestRunner_exports);
+var import_effect = require("effect");
+var StdError = __toESM(require("./StdError.js"), 1);
+const captureBase = "refs/flows/capture-base";
+const TestRunner = import_effect.Context.Service("@smthrs/std/TestRunner");
+const make = (runner) => TestRunner.of({ declared: import_effect.Effect.succeed(runner) });
+const makeNoop = () => TestRunner.of({
+  declared: import_effect.Effect.fail(
+    new StdError.StdError({
+      code: "provider_unavailable",
+      message: "No test runner is declared for this repository, so there is nothing for the test flow to run. Use bash with the command this project's own documentation gives."
+    })
+  )
+});
+const layer = (runner) => import_effect.Layer.succeed(TestRunner, make(runner));
+const layerNoop = import_effect.Layer.succeed(TestRunner, makeNoop());
+//# sourceMappingURL=TestRunner.js.map

package/dist/cjs/TestRunner.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/TestRunner.ts"],
+  "sourcesContent": ["/**\n * The repository's own test invocation, declared once by the host.\n *\n * Every repository already knows how to run its tests, and the harness is told\n * so at setup. What the measured program shows is what happens when that fact\n * is not a *callable* thing: agents guess labels\n * (`management_commands.test_flush`, `tests/related_lookup`, `test_axis.py` \u2014\n * none of which exist), and a guessed label costs a frame each time. Seven such\n * invocations are documented across the 45 instances.\n *\n * So the invocation is a declaration, not a parameter: a caller of the `test`\n * flow selects *which* tests, never *how* to run them.\n *\n * @since 1.0.0\n */\n\nimport { Context, Effect, Layer } from \"effect\"\nimport * as StdError from \"./StdError.ts\"\n\n/**\n * The default ref naming a tree as it stood before the agent touched it.\n *\n * The engine records the pristine checkout under this ref, so a baseline run\n * reuses what already exists instead of inventing a second notion of \"base\".\n *\n * @category constants\n * @since 1.0.0\n */\nexport const captureBase = \"refs/flows/capture-base\"\n\n/**\n * How this repository runs its tests.\n *\n * `cwd` is where the runner runs, and `root` is the host directory holding the\n * git repository. They differ exactly when the runner runs in a container: the\n * container sees the repository at `cwd`, the host sees it at `root`, and a\n * baseline checkout created at `<root>/<name>` is visible to the runner at\n * `<cwd>/<name>` because it is the same directory under two names.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface Runner {\n  /** The runner command line, without any test selection. */\n  readonly command: string\n  /** Where the runner runs; the container's path when `container` is set. */\n  readonly cwd?: string | undefined\n  /** The host path of the repository, when it differs from `cwd`. */\n  readonly root?: string | undefined\n  /** A container to route the run through, via the `Container` transport. */\n  readonly container?: string | undefined\n  /** Environment the runner needs. */\n  readonly env?: Record<string, string> | undefined\n  /** The ref whose commit is the pristine base; defaults to {@link captureBase}, then HEAD. */\n  readonly baseRef?: string | undefined\n  /** False refuses baseline requests before any process runs. */\n  readonly baseline?: false | undefined\n  /** Default wall-clock budget for one run. */\n  readonly timeoutMs?: number | undefined\n}\n\n/**\n * The declaration service.\n *\n * @category services\n * @since 1.0.0\n */\nexport interface TestRunner {\n  readonly declared: Effect.Effect<Runner, StdError.StdError>\n}\n\n/**\n * The {@link TestRunner} service tag.\n *\n * @category services\n * @since 1.0.0\n */\nexport const TestRunner: Context.Service<TestRunner, TestRunner> = Context.Service(\"@smthrs/std/TestRunner\")\n\n/**\n * Declares one repository's runner.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const make = (runner: Runner): TestRunner => TestRunner.of({ declared: Effect.succeed(runner) })\n\n/**\n * Declares that this host knows of no runner.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const makeNoop = (): TestRunner =>\n  TestRunner.of({\n    declared: Effect.fail(\n      new StdError.StdError({\n        code: \"provider_unavailable\",\n        message:\n          \"No test runner is declared for this repository, so there is nothing for the test flow to run. Use bash with the command this project's own documentation gives.\"\n      })\n    )\n  })\n\n/**\n * Provides {@link make}.\n *\n * @category layers\n * @since 1.0.0\n */\nexport const layer = (runner: Runner): Layer.Layer<TestRunner> => Layer.succeed(TestRunner, make(runner))\n\n/**\n * Provides {@link makeNoop}.\n *\n * @category layers\n * @since 1.0.0\n */\nexport const layerNoop: Layer.Layer<TestRunner> = Layer.succeed(TestRunner, makeNoop())\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAgBA,oBAAuC;AACvC,eAA0B;AAWnB,MAAM,cAAc;AAiDpB,MAAM,aAAsD,sBAAQ,QAAQ,wBAAwB;AAQpG,MAAM,OAAO,CAAC,WAA+B,WAAW,GAAG,EAAE,UAAU,qBAAO,QAAQ,MAAM,EAAE,CAAC;AAQ/F,MAAM,WAAW,MACtB,WAAW,GAAG;AAAA,EACZ,UAAU,qBAAO;AAAA,IACf,IAAI,SAAS,SAAS;AAAA,MACpB,MAAM;AAAA,MACN,SACE;AAAA,IACJ,CAAC;AAAA,EACH;AACF,CAAC;AAQI,MAAM,QAAQ,CAAC,WAA4C,oBAAM,QAAQ,YAAY,KAAK,MAAM,CAAC;AAQjG,MAAM,YAAqC,oBAAM,QAAQ,YAAY,SAAS,CAAC;",
+  "names": []
+}

package/dist/cjs/TreeFingerprint.d.ts

@@ -0,0 +1,140 @@
+/**
+ * The identity of one directory tree, measured where the tree is.
+ *
+ * `@smthrs/agent/WorkspaceObservation` measures the host workspace around
+ * every frame so the loop's mutation accounting is a fact rather than a
+ * claim. A command routed into a container writes to a filesystem that walk
+ * never sees: the SWE-bench rig bind-mounts the checkout into its container,
+ * so a container edit lands on the host too, but a container Harbor or Pier
+ * starts has no such mount, and every edit an agent made there read as an
+ * idle frame. Measured 2026-09-22 on Terminal-Bench 4.0: `read_only_cap`
+ * ended one run after twenty-four frames of container writes, and the claim
+ * judge refused another's completion as "work this run never recorded".
+ *
+ * This module is the same measurement taken inside the container: one POSIX
+ * shell script that lists every kept file under a directory with its size and
+ * modification time, in sorted order, and prints one checksum of the listing.
+ * `bash` runs it through the container transport before and after a
+ * containerised command and reports whether the two answers differ under the
+ * reserved {@link key}. The harness reads that key as a measured write, the
+ * way it reads `invalidProbe` as a measured refusal.
+ *
+ * The same properties as the host walk, and the same stated limits:
+ *
+ * - **Identity, not content.** Size and mtime per file; a rewrite that
+ *   restores both is invisible.
+ * - **Pruning is the signal.** {@link defaultPrune} and
+ *   {@link defaultIgnoreSuffixes} are the one list both measurements use, so
+ *   a derived artifact the host walk skips is skipped here too.
+ * - **A partial listing says so.** The listing stops at {@link maxPaths}, and
+ *   a measurement that stopped there reports `complete: false`; `bash` then
+ *   reports nothing rather than a guess.
+ * - **Every tool it needs is POSIX or busybox.** `find -prune`, `stat -c`,
+ *   `sort`, `head`, `cksum` and `grep -c` are in every Linux base image this
+ *   has been run against, GNU and busybox alike. A container that lacks one
+ *   answers with a non-zero exit, which is read as "unmeasured".
+ *
+ * @since 1.0.0
+ */
+/**
+ * The reserved output key a flow reports a measured write under.
+ *
+ * A wire contract with the harness rather than a shared type, exactly as
+ * `Probe.key` is: `@smthrs/harness` reads this key off a `Schema.Json` result
+ * and must not depend on the tool library to do it. `true` means the tree the
+ * call targeted differed after the call from before it; `false` means it was
+ * measured and held still; absent means it was not measured.
+ *
+ * @category identifiers
+ * @since 1.0.0
+ */
+export declare const key = "mutated";
+/**
+ * Directory names never descended into.
+ *
+ * Every entry is a place a tool writes derived state while the run is working:
+ * version-control internals, dependency trees, and the caches Python, Node,
+ * Rust and their test runners keep beside the sources. A run that changes only
+ * these has changed nothing it will be judged on.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export declare const defaultPrune: ReadonlyArray<string>;
+/**
+ * File and directory name suffixes left out of a measurement.
+ *
+ * Compiled output is the case that matters: several SWE-bench projects build
+ * extensions in place, which drops `.so` files next to the `.py` files they
+ * came from. Those move whenever the run executes its test suite, and
+ * counting them would report every probe as an edit.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export declare const defaultIgnoreSuffixes: ReadonlyArray<string>;
+/**
+ * The largest number of files one measurement covers.
+ *
+ * The same bound the host walk uses, for the same reason: a listing that
+ * stopped here covers a prefix chosen by sort order, and a prefix holding
+ * still says nothing about the files being edited outside it.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export declare const maxPaths = 50000;
+/**
+ * One measurement, as {@link parse} reads it off the script's output.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Measurement {
+    /** The checksum of the whole listing; equal for two measurements of an unchanged tree. */
+    readonly digest: string;
+    /** How many files the listing covered. */
+    readonly paths: number;
+    /** Whether the listing covered the whole tree rather than a bounded prefix. */
+    readonly complete: boolean;
+}
+/**
+ * The POSIX shell script that measures the current directory.
+ *
+ * Prints two lines: `cksum`'s `<crc> <bytes>` over the sorted listing, then
+ * the number of listing lines. The listing is capped one past
+ * {@link maxPaths} so the count alone says whether the bound was reached.
+ * Errors from `find` and `stat` are discarded: a path that vanished mid-walk
+ * is movement the next measurement reports, and a file the shell may not
+ * stat is one it could not have measured either way.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const script: (options?: {
+    readonly prune?: ReadonlyArray<string> | undefined;
+    readonly ignoreSuffixes?: ReadonlyArray<string> | undefined;
+}) => string;
+/**
+ * Reads one measurement off the script's standard output.
+ *
+ * `undefined` for anything that is not two well-formed lines: the script did
+ * not run, a tool it needs is missing, or the output was cut. An unmeasured
+ * tree is reported as unmeasured, never as unchanged.
+ *
+ * @category conversions
+ * @since 1.0.0
+ */
+export declare const parse: (stdout: string) => Measurement | undefined;
+/**
+ * Whether two measurements say the tree moved, or nothing at all.
+ *
+ * `true` and `false` are answers; `undefined` is the honest reading whenever
+ * either measurement is absent or bounded, because a prefix that held still
+ * is not a tree that held still.
+ *
+ * @category conversions
+ * @since 1.0.0
+ */
+export declare const moved: (before: Measurement | undefined, after: Measurement | undefined) => boolean | undefined;
+//# sourceMappingURL=TreeFingerprint.d.ts.map

package/dist/cjs/TreeFingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TreeFingerprint.d.ts","sourceRoot":"","sources":["../../src/TreeFingerprint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAIH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,GAAG,YAAY,CAAA;AAE5B;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,EAAE,aAAa,CAAC,MAAM,CAM9C,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,EAAE,aAAa,CAAC,MAAM,CAUvD,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ,QAAS,CAAA;AAE9B;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,0FAA0F;IAC1F,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAC3B;AAKD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,MAAM,GAAI,UAAS;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,CAAA;IAClD,QAAQ,CAAC,cAAc,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,CAAA;CACvD,KAAG,MAaR,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,KAAK,GAAI,QAAQ,MAAM,KAAG,WAAW,GAAG,SAapD,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,KAAK,GAChB,QAAQ,WAAW,GAAG,SAAS,EAC/B,OAAO,WAAW,GAAG,SAAS,KAC7B,OAAO,GAAG,SAGuB,CAAA"}