@paraharness/fs 0.0.0-stage → 0.2.0

package/dist/executors/create-fs-executors.js

@@ -0,0 +1,57 @@
+import { FsJsonlLessonStore } from '../stores/fs-jsonl-lesson-store.js';
+import { collectFsTelemetry, evaluateFsQuotaTripwire, executeFsRegexCheck, } from './fs-check-tripwire-and-telemetry.js';
+import { evaluateFsGlobEffectMatcher } from './fs-glob-effect-matcher.js';
+import { evaluateFsAllowOnlyGuard, evaluateFsBoundaryGuard, evaluateFsProtectGuard, evaluateFsReadOnlyGuard, } from './fs-path-guard-executors.js';
+import { createFsGlobToolDriver, createFsGrepToolDriver, createFsReadToolDriver, } from './fs-read-tool-drivers.js';
+import { executeFsGlobSource, executeFsTextSource, } from './fs-source-executors.js';
+import { evaluateFsRequireReadBeforeWriteGuard, evaluateFsScopedWriteGuard, evaluateFsSecretLiteralsGuard, evaluateFsWriteGuard, } from './fs-write-guard-executors.js';
+import { createFsEditToolDriver, createFsWriteToolDriver, } from './fs-write-tool-drivers.js';
+/**
+ * Creates a fresh `RuntimeExecutorRegistrySlice` registering all `@paraharness/fs` runtime executors and drivers.
+ *
+ * Registers `sources`, `checks`, `policyGuards`, `quotaTripwires`, `telemetryCollectors`,
+ * `effectMatchers`, `tools`, and `lessons` for `@paraharness/fs` AST nodes (`SPEC.md` §4.3).
+ *
+ * @returns {RuntimeExecutorRegistrySlice} Deeply frozen executor registry slice for `@paraharness/fs`.
+ */
+export function createFsExecutors() {
+    return Object.freeze({
+        sources: Object.freeze({
+            'fs:text-source': executeFsTextSource,
+            'fs:glob-source': executeFsGlobSource,
+        }),
+        checks: Object.freeze({
+            'fs:regex-check': executeFsRegexCheck,
+        }),
+        policyGuards: Object.freeze({
+            'fs:boundary-guard': evaluateFsBoundaryGuard,
+            'fs:protect': evaluateFsProtectGuard,
+            'fs:read-only': evaluateFsReadOnlyGuard,
+            'fs:allow-only': evaluateFsAllowOnlyGuard,
+            'fs:write-guard': evaluateFsWriteGuard,
+            'fs:require-read-before-write': evaluateFsRequireReadBeforeWriteGuard,
+            'fs:scoped-write': evaluateFsScopedWriteGuard,
+            'fs:secret-literals': evaluateFsSecretLiteralsGuard,
+        }),
+        quotaTripwires: Object.freeze({
+            'fs:quota-tripwire': evaluateFsQuotaTripwire,
+        }),
+        telemetryCollectors: Object.freeze({
+            'fs:telemetry': collectFsTelemetry,
+        }),
+        effectMatchers: Object.freeze({
+            'fs:match-globs': evaluateFsGlobEffectMatcher,
+        }),
+        tools: Object.freeze({
+            'fs:read': createFsReadToolDriver(),
+            'fs:edit': createFsEditToolDriver(),
+            'fs:write': createFsWriteToolDriver(),
+            'fs:glob': createFsGlobToolDriver(),
+            'fs:grep': createFsGrepToolDriver(),
+        }),
+        lessons: Object.freeze({
+            'fs:jsonl-lesson-store': (node) => new FsJsonlLessonStore(node),
+        }),
+    });
+}
+//# sourceMappingURL=create-fs-executors.js.map

package/dist/executors/create-fs-executors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-fs-executors.js","sourceRoot":"","sources":["../../src/executors/create-fs-executors.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AACxE,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AAC1E,OAAO,EACL,wBAAwB,EACxB,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,qCAAqC,EACrC,0BAA0B,EAC1B,6BAA6B,EAC7B,oBAAoB,GACrB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,4BAA4B,CAAC;AAEpC;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,MAAM,CAAC,MAAM,CAA+B;QACjD,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC;YACrB,gBAAgB,EAAE,mBAAmB;YACrC,gBAAgB,EAAE,mBAAmB;SACtC,CAAC;QACF,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;YACpB,gBAAgB,EAAE,mBAAmB;SACtC,CAAC;QACF,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC;YAC1B,mBAAmB,EAAE,uBAAuB;YAC5C,YAAY,EAAE,sBAAsB;YACpC,cAAc,EAAE,uBAAuB;YACvC,eAAe,EAAE,wBAAwB;YACzC,gBAAgB,EAAE,oBAAoB;YACtC,8BAA8B,EAAE,qCAAqC;YACrE,iBAAiB,EAAE,0BAA0B;YAC7C,oBAAoB,EAAE,6BAA6B;SACpD,CAAC;QACF,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC;YAC5B,mBAAmB,EAAE,uBAAuB;SAC7C,CAAC;QACF,mBAAmB,EAAE,MAAM,CAAC,MAAM,CAAC;YACjC,cAAc,EAAE,kBAAkB;SACnC,CAAC;QACF,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC;YAC5B,gBAAgB,EAAE,2BAA2B;SAC9C,CAAC;QACF,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC;YACnB,SAAS,EAAE,sBAAsB,EAAE;YACnC,SAAS,EAAE,sBAAsB,EAAE;YACnC,UAAU,EAAE,uBAAuB,EAAE;YACrC,SAAS,EAAE,sBAAsB,EAAE;YACnC,SAAS,EAAE,sBAAsB,EAAE;SACpC,CAAC;QACF,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC;YACrB,uBAAuB,EAAE,CAAC,IAA4B,EAAsB,EAAE,CAC5E,IAAI,kBAAkB,CAAC,IAAI,CAAC;SAC/B,CAAC;KACH,CAAC,CAAC;AACL,CAAC"}

package/dist/executors/fs-check-tripwire-and-telemetry.d.ts

@@ -0,0 +1,45 @@
+import type { CheckEvaluationResult, FsQuotaTripwireNode, FsRegexCheckNode, FsTelemetryCollectorNode, QuotaTripwireEvaluationInput, QuotaTripwireEvaluationResult, StepExecutionContext, ToolEffect } from '@paraharness/core';
+/**
+ * Evaluates an `FsRegexCheckNode` (`fs:regex-check`) strictly over mutated files matching `targetGlobs` (`SPEC.md` §4.3).
+ *
+ * Inspects files mutated in `ctx.observedEffects` or modified since `scopeHandle.baseRef` so
+ * pre-existing untouched repository files never trigger false deficits.
+ *
+ * @template THandle Runtime handle type of the active isolation scope.
+ *
+ * @param {FsRegexCheckNode<THandle>}     node   - Passive regex check AST node.
+ * @param {void}                          _input - Unused check input parameter.
+ * @param {StepExecutionContext<THandle>} ctx    - Step execution context.
+ *
+ * @returns {Promise<CheckEvaluationResult>} Check evaluation result with any matched deficits.
+ */
+export declare function executeFsRegexCheck<THandle = unknown>(node: FsRegexCheckNode<THandle>, _input: void, ctx: StepExecutionContext<THandle>): Promise<CheckEvaluationResult>;
+/**
+ * Evaluates an `FsQuotaTripwireNode` (`fs:quota-tripwire`) after tool execution (`SPEC.md` §4.3).
+ *
+ * Trips when the total count of distinct mutated file paths across `accumulatedEffects`
+ * and `newEffects` exceeds `node.maxFilesMutated`.
+ *
+ * @param {FsQuotaTripwireNode}           node  - Quota tripwire AST node.
+ * @param {QuotaTripwireEvaluationInput}  input - Accumulated and newly recorded tool effects.
+ * @param {StepExecutionContext<unknown>} _ctx  - Step execution context.
+ *
+ * @returns {QuotaTripwireEvaluationResult} Tripwire result indicating whether the quota was exceeded.
+ */
+export declare function evaluateFsQuotaTripwire(node: FsQuotaTripwireNode, input: QuotaTripwireEvaluationInput, _ctx: StepExecutionContext<unknown>): QuotaTripwireEvaluationResult;
+/**
+ * Collects deduplicated `filesRead` and `filesMutated` arrays from `observedEffects` (`fs:telemetry`).
+ *
+ * Populates `UniversalStepTelemetry.custom` for step receipts and interrupt mappers (`SPEC.md` §4.3).
+ *
+ * @param {FsTelemetryCollectorNode}      _node           - Telemetry collector AST node.
+ * @param {readonly ToolEffect[]}         observedEffects - Observed tool effects in the step session.
+ * @param {StepExecutionContext<unknown>} _ctx            - Step execution context.
+ *
+ * @returns {{ readonly filesRead: readonly string[]; readonly filesMutated: readonly string[] }} Frozen telemetry metrics object.
+ */
+export declare function collectFsTelemetry(_node: FsTelemetryCollectorNode, observedEffects: readonly ToolEffect[], _ctx: StepExecutionContext<unknown>): {
+    readonly filesRead: readonly string[];
+    readonly filesMutated: readonly string[];
+};
+//# sourceMappingURL=fs-check-tripwire-and-telemetry.d.ts.map

package/dist/executors/fs-check-tripwire-and-telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-check-tripwire-and-telemetry.d.ts","sourceRoot":"","sources":["../../src/executors/fs-check-tripwire-and-telemetry.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,wBAAwB,EACxB,4BAA4B,EAC5B,6BAA6B,EAC7B,oBAAoB,EACpB,UAAU,EACX,MAAM,mBAAmB,CAAC;AAM3B;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,GAAG,OAAO,EACzD,IAAI,EAAE,gBAAgB,CAAC,OAAO,CAAC,EAC/B,MAAM,EAAE,IAAI,EACZ,GAAG,EAAE,oBAAoB,CAAC,OAAO,CAAC,GACjC,OAAO,CAAC,qBAAqB,CAAC,CAmBhC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,mBAAmB,EACzB,KAAK,EAAE,4BAA4B,EACnC,IAAI,EAAE,oBAAoB,CAAC,OAAO,CAAC,GAClC,6BAA6B,CAW/B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,wBAAwB,EAC/B,eAAe,EAAE,SAAS,UAAU,EAAE,EACtC,IAAI,EAAE,oBAAoB,CAAC,OAAO,CAAC,GAClC;IAAE,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAiBrF"}

package/dist/executors/fs-check-tripwire-and-telemetry.js

@@ -0,0 +1,99 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { addMutatedPathsFromEffects } from './internal/add-mutated-paths-from-effects.js';
+import { collectMutatedPathsSinceBaseRef } from './internal/collect-mutated-paths-since-base-ref.js';
+import { compileGlobOrExactMatcher } from './internal/compile-glob-or-exact-matcher.js';
+import { resolveJailedWorktreePath } from './internal/resolve-jailed-worktree-path.js';
+/**
+ * Evaluates an `FsRegexCheckNode` (`fs:regex-check`) strictly over mutated files matching `targetGlobs` (`SPEC.md` §4.3).
+ *
+ * Inspects files mutated in `ctx.observedEffects` or modified since `scopeHandle.baseRef` so
+ * pre-existing untouched repository files never trigger false deficits.
+ *
+ * @template THandle Runtime handle type of the active isolation scope.
+ *
+ * @param {FsRegexCheckNode<THandle>}     node   - Passive regex check AST node.
+ * @param {void}                          _input - Unused check input parameter.
+ * @param {StepExecutionContext<THandle>} ctx    - Step execution context.
+ *
+ * @returns {Promise<CheckEvaluationResult>} Check evaluation result with any matched deficits.
+ */
+export async function executeFsRegexCheck(node, _input, ctx) {
+    const mutatedPaths = collectMutatedPathsSinceBaseRef(ctx.observedEffects, ctx.scopeHandle);
+    const isTargetMatch = compileGlobOrExactMatcher(node.targetGlobs);
+    const cleanFlags = (node.forbidFlags ?? '').replace(/g/g, '');
+    const forbidRegex = new RegExp(node.forbidPattern, cleanFlags);
+    const deficits = [];
+    for (const relPath of mutatedPaths) {
+        if (!isTargetMatch(relPath))
+            continue;
+        const { absolutePath } = resolveJailedWorktreePath(ctx.scopeHandle, relPath, 'read');
+        if (!existsSync(absolutePath))
+            continue;
+        const content = await readFile(absolutePath, 'utf8');
+        if (forbidRegex.test(content)) {
+            deficits.push(`${relPath}: ${node.violationMessage}`);
+        }
+    }
+    return Object.freeze({
+        ok: deficits.length === 0,
+        deficits: Object.freeze(deficits),
+    });
+}
+/**
+ * Evaluates an `FsQuotaTripwireNode` (`fs:quota-tripwire`) after tool execution (`SPEC.md` §4.3).
+ *
+ * Trips when the total count of distinct mutated file paths across `accumulatedEffects`
+ * and `newEffects` exceeds `node.maxFilesMutated`.
+ *
+ * @param {FsQuotaTripwireNode}           node  - Quota tripwire AST node.
+ * @param {QuotaTripwireEvaluationInput}  input - Accumulated and newly recorded tool effects.
+ * @param {StepExecutionContext<unknown>} _ctx  - Step execution context.
+ *
+ * @returns {QuotaTripwireEvaluationResult} Tripwire result indicating whether the quota was exceeded.
+ */
+export function evaluateFsQuotaTripwire(node, input, _ctx) {
+    const mutatedPaths = new Set();
+    addMutatedPathsFromEffects(input.accumulatedEffects, mutatedPaths);
+    addMutatedPathsFromEffects(input.newEffects, mutatedPaths);
+    if (mutatedPaths.size > node.maxFilesMutated) {
+        return Object.freeze({
+            tripped: true,
+            reason: `Mutated ${String(mutatedPaths.size)} distinct files, exceeding maxFilesMutated(${String(node.maxFilesMutated)}).`,
+        });
+    }
+    return Object.freeze({ tripped: false });
+}
+/**
+ * Collects deduplicated `filesRead` and `filesMutated` arrays from `observedEffects` (`fs:telemetry`).
+ *
+ * Populates `UniversalStepTelemetry.custom` for step receipts and interrupt mappers (`SPEC.md` §4.3).
+ *
+ * @param {FsTelemetryCollectorNode}      _node           - Telemetry collector AST node.
+ * @param {readonly ToolEffect[]}         observedEffects - Observed tool effects in the step session.
+ * @param {StepExecutionContext<unknown>} _ctx            - Step execution context.
+ *
+ * @returns {{ readonly filesRead: readonly string[]; readonly filesMutated: readonly string[] }} Frozen telemetry metrics object.
+ */
+export function collectFsTelemetry(_node, observedEffects, _ctx) {
+    const filesRead = new Set();
+    const filesMutated = new Set();
+    for (const eff of observedEffects) {
+        if (eff.kind !== 'fs:effect')
+            continue;
+        const mode = eff.attributes?.['mode'];
+        const paths = eff.attributes?.['paths'];
+        if (!Array.isArray(paths))
+            continue;
+        const targetSet = eff.mutatesScope === true || mode === 'write' ? filesMutated : filesRead;
+        for (const p of paths) {
+            if (typeof p === 'string')
+                targetSet.add(p.replace(/\\/g, '/').replace(/^\.\//, ''));
+        }
+    }
+    return Object.freeze({
+        filesRead: Object.freeze([...filesRead]),
+        filesMutated: Object.freeze([...filesMutated]),
+    });
+}
+//# sourceMappingURL=fs-check-tripwire-and-telemetry.js.map

package/dist/executors/fs-check-tripwire-and-telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-check-tripwire-and-telemetry.js","sourceRoot":"","sources":["../../src/executors/fs-check-tripwire-and-telemetry.ts"],"names":[],"mappings":"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"}

package/dist/executors/fs-executors.constants.d.ts

@@ -0,0 +1,10 @@
+import type { RuntimeExecutorRegistrySlice } from '@paraharness/core';
+/**
+ * Default frozen `RuntimeExecutorRegistrySlice` instance for `@paraharness/fs`.
+ *
+ * Pass to `createExecutorRegistry(fsExecutors, ...)` to register all `@paraharness/fs`
+ * sources, checks, policy guards, tripwires, telemetry collectors, effect matchers,
+ * tool drivers, and lesson stores.
+ */
+export declare const fsExecutors: RuntimeExecutorRegistrySlice;
+//# sourceMappingURL=fs-executors.constants.d.ts.map

package/dist/executors/fs-executors.constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-executors.constants.d.ts","sourceRoot":"","sources":["../../src/executors/fs-executors.constants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,mBAAmB,CAAC;AAGtE;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,EAAE,4BAAkD,CAAC"}

package/dist/executors/fs-executors.constants.js

@@ -0,0 +1,10 @@
+import { createFsExecutors } from './create-fs-executors.js';
+/**
+ * Default frozen `RuntimeExecutorRegistrySlice` instance for `@paraharness/fs`.
+ *
+ * Pass to `createExecutorRegistry(fsExecutors, ...)` to register all `@paraharness/fs`
+ * sources, checks, policy guards, tripwires, telemetry collectors, effect matchers,
+ * tool drivers, and lesson stores.
+ */
+export const fsExecutors = createFsExecutors();
+//# sourceMappingURL=fs-executors.constants.js.map

package/dist/executors/fs-executors.constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-executors.constants.js","sourceRoot":"","sources":["../../src/executors/fs-executors.constants.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,WAAW,GAAiC,iBAAiB,EAAE,CAAC"}

package/dist/executors/fs-glob-effect-matcher.d.ts

@@ -0,0 +1,15 @@
+import type { FsGlobMatcherNode, StepExecutionContext, ToolEffect } from '@paraharness/core';
+/**
+ * Evaluates an `FsGlobMatcherNode` (`fs:match-globs`) against a `ToolEffect` (`SPEC.md` §3.5 & §4.3).
+ *
+ * Matches both exact normalized file paths (including bracketed routes like `app/users/[id]/page.test.tsx`)
+ * and `picomatch` glob patterns, checking access mode compatibility (`'read' | 'write' | 'any'`).
+ *
+ * @param {FsGlobMatcherNode}             node   - Passive glob matcher AST node.
+ * @param {ToolEffect}                    effect - Observed or proposed tool effect to test.
+ * @param {StepExecutionContext<unknown>} _ctx   - Step execution context.
+ *
+ * @returns {boolean} True when `effect` is a matching `fs:effect` covered by `node`.
+ */
+export declare function evaluateFsGlobEffectMatcher(node: FsGlobMatcherNode, effect: ToolEffect, _ctx: StepExecutionContext<unknown>): boolean;
+//# sourceMappingURL=fs-glob-effect-matcher.d.ts.map

package/dist/executors/fs-glob-effect-matcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-glob-effect-matcher.d.ts","sourceRoot":"","sources":["../../src/executors/fs-glob-effect-matcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EACjB,oBAAoB,EACpB,UAAU,EACX,MAAM,mBAAmB,CAAC;AAG3B;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,iBAAiB,EACvB,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,oBAAoB,CAAC,OAAO,CAAC,GAClC,OAAO,CAsBT"}

package/dist/executors/fs-glob-effect-matcher.js

@@ -0,0 +1,37 @@
+import { compileGlobOrExactMatcher } from './internal/compile-glob-or-exact-matcher.js';
+/**
+ * Evaluates an `FsGlobMatcherNode` (`fs:match-globs`) against a `ToolEffect` (`SPEC.md` §3.5 & §4.3).
+ *
+ * Matches both exact normalized file paths (including bracketed routes like `app/users/[id]/page.test.tsx`)
+ * and `picomatch` glob patterns, checking access mode compatibility (`'read' | 'write' | 'any'`).
+ *
+ * @param {FsGlobMatcherNode}             node   - Passive glob matcher AST node.
+ * @param {ToolEffect}                    effect - Observed or proposed tool effect to test.
+ * @param {StepExecutionContext<unknown>} _ctx   - Step execution context.
+ *
+ * @returns {boolean} True when `effect` is a matching `fs:effect` covered by `node`.
+ */
+export function evaluateFsGlobEffectMatcher(node, effect, _ctx) {
+    if (effect.kind !== 'fs:effect') {
+        return false;
+    }
+    const effectMode = effect.attributes?.['mode'];
+    if (node.mode === 'read' && effectMode !== 'read') {
+        return false;
+    }
+    if (node.mode === 'write' && effectMode !== 'write' && effect.mutatesScope !== true) {
+        return false;
+    }
+    const rawPaths = effect.attributes?.['paths'];
+    if (!Array.isArray(rawPaths) || rawPaths.length === 0) {
+        return false;
+    }
+    const isMatch = compileGlobOrExactMatcher(node.globs);
+    for (const rawPath of rawPaths) {
+        if (typeof rawPath === 'string' && isMatch(rawPath)) {
+            return true;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=fs-glob-effect-matcher.js.map

package/dist/executors/fs-glob-effect-matcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-glob-effect-matcher.js","sourceRoot":"","sources":["../../src/executors/fs-glob-effect-matcher.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,yBAAyB,EAAE,MAAM,6CAA6C,CAAC;AAExF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,2BAA2B,CACzC,IAAuB,EACvB,MAAkB,EAClB,IAAmC;IAEnC,IAAI,MAAM,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QAChC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC,MAAM,CAAC,CAAC;IAC/C,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,UAAU,KAAK,MAAM,EAAE,CAAC;QAClD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,IAAI,UAAU,KAAK,OAAO,IAAI,MAAM,CAAC,YAAY,KAAK,IAAI,EAAE,CAAC;QACpF,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC,OAAO,CAAC,CAAC;IAC9C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,OAAO,GAAG,yBAAyB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACtD,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YACpD,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/executors/fs-path-guard-executors.d.ts

@@ -0,0 +1,51 @@
+import type { FsAllowOnlyGuardNode, FsBoundaryGuardNode, FsProtectGuardNode, FsReadOnlyGuardNode, PolicyGuardEvaluationInput, PolicyGuardEvaluationResult, StepExecutionContext } from '@paraharness/core';
+/**
+ * Evaluates an `FsBoundaryGuardNode` (`fs:boundary-guard`) against proposed tool effects (`SPEC.md` §4.3).
+ *
+ * Blocks any write effect matching a partition's `boundaryGlobs` unless covered by `input.activeLeases`,
+ * projecting `violatedEffects` strictly to the violating boundary file paths.
+ *
+ * @param {FsBoundaryGuardNode}           node  - Boundary guard AST node.
+ * @param {PolicyGuardEvaluationInput}    input - Tool name, proposed effects, and active leases.
+ * @param {StepExecutionContext<unknown>} _ctx  - Step execution context.
+ *
+ * @returns {PolicyGuardEvaluationResult} Guard evaluation result and projected `violatedEffects`.
+ */
+export declare function evaluateFsBoundaryGuard(node: FsBoundaryGuardNode, input: PolicyGuardEvaluationInput, _ctx: StepExecutionContext<unknown>): PolicyGuardEvaluationResult;
+/**
+ * Evaluates an `FsProtectGuardNode` (`fs:protect`) against proposed tool effects (`SPEC.md` §4.3).
+ *
+ * Rejects write mutations targeting paths matching `node.globs` unless covered by `input.activeLeases`.
+ *
+ * @param {FsProtectGuardNode}            node  - Protect guard AST node.
+ * @param {PolicyGuardEvaluationInput}    input - Tool name, proposed effects, and active leases.
+ * @param {StepExecutionContext<unknown>} _ctx  - Step execution context.
+ *
+ * @returns {PolicyGuardEvaluationResult} Guard evaluation result and projected `violatedEffects`.
+ */
+export declare function evaluateFsProtectGuard(node: FsProtectGuardNode, input: PolicyGuardEvaluationInput, _ctx: StepExecutionContext<unknown>): PolicyGuardEvaluationResult;
+/**
+ * Evaluates an `FsReadOnlyGuardNode` (`fs:read-only`) against proposed tool effects (`SPEC.md` §4.3).
+ *
+ * Rejects all filesystem write mutations not explicitly covered by `input.activeLeases`.
+ *
+ * @param {FsReadOnlyGuardNode}           _node - Read-only guard AST node.
+ * @param {PolicyGuardEvaluationInput}    input - Tool name, proposed effects, and active leases.
+ * @param {StepExecutionContext<unknown>} _ctx  - Step execution context.
+ *
+ * @returns {PolicyGuardEvaluationResult} Guard evaluation result and projected `violatedEffects`.
+ */
+export declare function evaluateFsReadOnlyGuard(_node: FsReadOnlyGuardNode, input: PolicyGuardEvaluationInput, _ctx: StepExecutionContext<unknown>): PolicyGuardEvaluationResult;
+/**
+ * Evaluates an `FsAllowOnlyGuardNode` (`fs:allow-only`) against proposed tool effects (`SPEC.md` §4.3).
+ *
+ * Rejects any write mutation whose path does not match `node.globs` (or `input.activeLeases`).
+ *
+ * @param {FsAllowOnlyGuardNode}          node  - Allow-only guard AST node.
+ * @param {PolicyGuardEvaluationInput}    input - Tool name, proposed effects, and active leases.
+ * @param {StepExecutionContext<unknown>} _ctx  - Step execution context.
+ *
+ * @returns {PolicyGuardEvaluationResult} Guard evaluation result and projected `violatedEffects`.
+ */
+export declare function evaluateFsAllowOnlyGuard(node: FsAllowOnlyGuardNode, input: PolicyGuardEvaluationInput, _ctx: StepExecutionContext<unknown>): PolicyGuardEvaluationResult;
+//# sourceMappingURL=fs-path-guard-executors.d.ts.map

package/dist/executors/fs-path-guard-executors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-path-guard-executors.d.ts","sourceRoot":"","sources":["../../src/executors/fs-path-guard-executors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,0BAA0B,EAC1B,2BAA2B,EAC3B,oBAAoB,EACrB,MAAM,mBAAmB,CAAC;AAQ3B;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,mBAAmB,EACzB,KAAK,EAAE,0BAA0B,EACjC,IAAI,EAAE,oBAAoB,CAAC,OAAO,CAAC,GAClC,2BAA2B,CAE7B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,kBAAkB,EACxB,KAAK,EAAE,0BAA0B,EACjC,IAAI,EAAE,oBAAoB,CAAC,OAAO,CAAC,GAClC,2BAA2B,CAE7B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,mBAAmB,EAC1B,KAAK,EAAE,0BAA0B,EACjC,IAAI,EAAE,oBAAoB,CAAC,OAAO,CAAC,GAClC,2BAA2B,CAE7B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,oBAAoB,EAC1B,KAAK,EAAE,0BAA0B,EACjC,IAAI,EAAE,oBAAoB,CAAC,OAAO,CAAC,GAClC,2BAA2B,CAE7B"}

package/dist/executors/fs-path-guard-executors.js

@@ -0,0 +1,60 @@
+import { evaluateFsAllowOnlyPaths, evaluateFsProtectPaths, evaluateFsReadOnlyPaths, } from './internal/evaluate-fs-allow-and-protect-guards.js';
+import { evaluateFsBoundaryPaths } from './internal/evaluate-fs-write-and-boundary-guards.js';
+/**
+ * Evaluates an `FsBoundaryGuardNode` (`fs:boundary-guard`) against proposed tool effects (`SPEC.md` §4.3).
+ *
+ * Blocks any write effect matching a partition's `boundaryGlobs` unless covered by `input.activeLeases`,
+ * projecting `violatedEffects` strictly to the violating boundary file paths.
+ *
+ * @param {FsBoundaryGuardNode}           node  - Boundary guard AST node.
+ * @param {PolicyGuardEvaluationInput}    input - Tool name, proposed effects, and active leases.
+ * @param {StepExecutionContext<unknown>} _ctx  - Step execution context.
+ *
+ * @returns {PolicyGuardEvaluationResult} Guard evaluation result and projected `violatedEffects`.
+ */
+export function evaluateFsBoundaryGuard(node, input, _ctx) {
+    return evaluateFsBoundaryPaths(node, input);
+}
+/**
+ * Evaluates an `FsProtectGuardNode` (`fs:protect`) against proposed tool effects (`SPEC.md` §4.3).
+ *
+ * Rejects write mutations targeting paths matching `node.globs` unless covered by `input.activeLeases`.
+ *
+ * @param {FsProtectGuardNode}            node  - Protect guard AST node.
+ * @param {PolicyGuardEvaluationInput}    input - Tool name, proposed effects, and active leases.
+ * @param {StepExecutionContext<unknown>} _ctx  - Step execution context.
+ *
+ * @returns {PolicyGuardEvaluationResult} Guard evaluation result and projected `violatedEffects`.
+ */
+export function evaluateFsProtectGuard(node, input, _ctx) {
+    return evaluateFsProtectPaths(node, input);
+}
+/**
+ * Evaluates an `FsReadOnlyGuardNode` (`fs:read-only`) against proposed tool effects (`SPEC.md` §4.3).
+ *
+ * Rejects all filesystem write mutations not explicitly covered by `input.activeLeases`.
+ *
+ * @param {FsReadOnlyGuardNode}           _node - Read-only guard AST node.
+ * @param {PolicyGuardEvaluationInput}    input - Tool name, proposed effects, and active leases.
+ * @param {StepExecutionContext<unknown>} _ctx  - Step execution context.
+ *
+ * @returns {PolicyGuardEvaluationResult} Guard evaluation result and projected `violatedEffects`.
+ */
+export function evaluateFsReadOnlyGuard(_node, input, _ctx) {
+    return evaluateFsReadOnlyPaths(input);
+}
+/**
+ * Evaluates an `FsAllowOnlyGuardNode` (`fs:allow-only`) against proposed tool effects (`SPEC.md` §4.3).
+ *
+ * Rejects any write mutation whose path does not match `node.globs` (or `input.activeLeases`).
+ *
+ * @param {FsAllowOnlyGuardNode}          node  - Allow-only guard AST node.
+ * @param {PolicyGuardEvaluationInput}    input - Tool name, proposed effects, and active leases.
+ * @param {StepExecutionContext<unknown>} _ctx  - Step execution context.
+ *
+ * @returns {PolicyGuardEvaluationResult} Guard evaluation result and projected `violatedEffects`.
+ */
+export function evaluateFsAllowOnlyGuard(node, input, _ctx) {
+    return evaluateFsAllowOnlyPaths(node, input);
+}
+//# sourceMappingURL=fs-path-guard-executors.js.map

package/dist/executors/fs-path-guard-executors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-path-guard-executors.js","sourceRoot":"","sources":["../../src/executors/fs-path-guard-executors.ts"],"names":[],"mappings":"AASA,OAAO,EACL,wBAAwB,EACxB,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,oDAAoD,CAAC;AAC5D,OAAO,EAAE,uBAAuB,EAAE,MAAM,qDAAqD,CAAC;AAE9F;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,uBAAuB,CACrC,IAAyB,EACzB,KAAiC,EACjC,IAAmC;IAEnC,OAAO,uBAAuB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,sBAAsB,CACpC,IAAwB,EACxB,KAAiC,EACjC,IAAmC;IAEnC,OAAO,sBAAsB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,uBAAuB,CACrC,KAA0B,EAC1B,KAAiC,EACjC,IAAmC;IAEnC,OAAO,uBAAuB,CAAC,KAAK,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,wBAAwB,CACtC,IAA0B,EAC1B,KAAiC,EACjC,IAAmC;IAEnC,OAAO,wBAAwB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AAC/C,CAAC"}

package/dist/executors/fs-read-tool-drivers.d.ts

@@ -0,0 +1,35 @@
+import type { FsGlobToolNode, FsGrepToolNode, FsReadToolNode, ToolDriver } from '@paraharness/core';
+/**
+ * Creates the workspace-jailed `ToolDriver` for `FsReadToolNode` (`fs:read` / `read_file`).
+ *
+ * Emits synchronous `FsToolEffect` read records (`mutatesScope: false`) and reads UTF-8
+ * file text after verifying `realpathSync` containment inside the active worktree.
+ *
+ * @template THandle Runtime handle type of the active isolation scope.
+ *
+ * @returns {ToolDriver<FsReadToolNode<THandle>, THandle>} Frozen `fs:read` tool driver.
+ */
+export declare function createFsReadToolDriver<THandle = unknown>(): ToolDriver<FsReadToolNode<THandle>, THandle>;
+/**
+ * Creates the workspace-jailed `ToolDriver` for `FsGlobToolNode` (`fs:glob` / `glob_files`).
+ *
+ * Enumerates workspace-relative files matching `args.pattern` in lexicographical order
+ * and records accessed file paths in a read-mode `FsToolEffect`.
+ *
+ * @template THandle Runtime handle type of the active isolation scope.
+ *
+ * @returns {ToolDriver<FsGlobToolNode<THandle>, THandle>} Frozen `fs:glob` tool driver.
+ */
+export declare function createFsGlobToolDriver<THandle = unknown>(): ToolDriver<FsGlobToolNode<THandle>, THandle>;
+/**
+ * Creates the workspace-jailed `ToolDriver` for `FsGrepToolNode` (`fs:grep` / `grep_files`).
+ *
+ * Searches workspace files matching `args.glob` against regular expression `args.pattern`
+ * and formats matching lines as `path:lineNumber:lineText`.
+ *
+ * @template THandle Runtime handle type of the active isolation scope.
+ *
+ * @returns {ToolDriver<FsGrepToolNode<THandle>, THandle>} Frozen `fs:grep` tool driver.
+ */
+export declare function createFsGrepToolDriver<THandle = unknown>(): ToolDriver<FsGrepToolNode<THandle>, THandle>;
+//# sourceMappingURL=fs-read-tool-drivers.d.ts.map

package/dist/executors/fs-read-tool-drivers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-read-tool-drivers.d.ts","sourceRoot":"","sources":["../../src/executors/fs-read-tool-drivers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EACd,cAAc,EAEd,UAAU,EAGX,MAAM,mBAAmB,CAAC;AAW3B;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,GAAG,OAAO,KAAK,UAAU,CACrE,cAAc,CAAC,OAAO,CAAC,EACvB,OAAO,CACR,CAWA;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,GAAG,OAAO,KAAK,UAAU,CACrE,cAAc,CAAC,OAAO,CAAC,EACvB,OAAO,CACR,CAWA;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,GAAG,OAAO,KAAK,UAAU,CACrE,cAAc,CAAC,OAAO,CAAC,EACvB,OAAO,CACR,CAWA"}

package/dist/executors/fs-read-tool-drivers.js

@@ -0,0 +1,73 @@
+import { createFsReadEffect } from './internal/create-fs-read-effect.js';
+import { enumerateWorkspaceFilesSync } from './internal/enumerate-workspace-files-sync.js';
+import { extractWorktreeRootAndBaseRef } from './internal/extract-worktree-root-and-base-ref.js';
+import { readFsToolFile } from './internal/fs-coding-tool-drivers.js';
+import { globFsToolFiles, grepFsToolFiles, } from './internal/fs-search-tool-drivers.js';
+import { resolveJailedWorktreePath } from './internal/resolve-jailed-worktree-path.js';
+/**
+ * Creates the workspace-jailed `ToolDriver` for `FsReadToolNode` (`fs:read` / `read_file`).
+ *
+ * Emits synchronous `FsToolEffect` read records (`mutatesScope: false`) and reads UTF-8
+ * file text after verifying `realpathSync` containment inside the active worktree.
+ *
+ * @template THandle Runtime handle type of the active isolation scope.
+ *
+ * @returns {ToolDriver<FsReadToolNode<THandle>, THandle>} Frozen `fs:read` tool driver.
+ */
+export function createFsReadToolDriver() {
+    return Object.freeze({
+        describeEffects(_node, args, scopeHandle) {
+            const rawPath = args?.path ?? '';
+            const { normalizedRelPath } = resolveJailedWorktreePath(scopeHandle, rawPath, 'read');
+            return Object.freeze([createFsReadEffect([normalizedRelPath])]);
+        },
+        execute(node, args, ctx) {
+            return readFsToolFile(node, args, ctx);
+        },
+    });
+}
+/**
+ * Creates the workspace-jailed `ToolDriver` for `FsGlobToolNode` (`fs:glob` / `glob_files`).
+ *
+ * Enumerates workspace-relative files matching `args.pattern` in lexicographical order
+ * and records accessed file paths in a read-mode `FsToolEffect`.
+ *
+ * @template THandle Runtime handle type of the active isolation scope.
+ *
+ * @returns {ToolDriver<FsGlobToolNode<THandle>, THandle>} Frozen `fs:glob` tool driver.
+ */
+export function createFsGlobToolDriver() {
+    return Object.freeze({
+        describeEffects(_node, args, scopeHandle) {
+            const pattern = args?.pattern ?? '**/*';
+            const { rootPath } = extractWorktreeRootAndBaseRef(scopeHandle);
+            return Object.freeze([createFsReadEffect(enumerateWorkspaceFilesSync(rootPath, pattern))]);
+        },
+        execute(node, args, ctx) {
+            return globFsToolFiles(node, args, ctx);
+        },
+    });
+}
+/**
+ * Creates the workspace-jailed `ToolDriver` for `FsGrepToolNode` (`fs:grep` / `grep_files`).
+ *
+ * Searches workspace files matching `args.glob` against regular expression `args.pattern`
+ * and formats matching lines as `path:lineNumber:lineText`.
+ *
+ * @template THandle Runtime handle type of the active isolation scope.
+ *
+ * @returns {ToolDriver<FsGrepToolNode<THandle>, THandle>} Frozen `fs:grep` tool driver.
+ */
+export function createFsGrepToolDriver() {
+    return Object.freeze({
+        describeEffects(_node, args, scopeHandle) {
+            const glob = args?.glob ?? '**/*';
+            const { rootPath } = extractWorktreeRootAndBaseRef(scopeHandle);
+            return Object.freeze([createFsReadEffect(enumerateWorkspaceFilesSync(rootPath, glob))]);
+        },
+        execute(node, args, ctx) {
+            return grepFsToolFiles(node, args, ctx);
+        },
+    });
+}
+//# sourceMappingURL=fs-read-tool-drivers.js.map

package/dist/executors/fs-read-tool-drivers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-read-tool-drivers.js","sourceRoot":"","sources":["../../src/executors/fs-read-tool-drivers.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AACzE,OAAO,EAAE,2BAA2B,EAAE,MAAM,8CAA8C,CAAC;AAC3F,OAAO,EAAE,6BAA6B,EAAE,MAAM,kDAAkD,CAAC;AACjG,OAAO,EAAE,cAAc,EAAE,MAAM,sCAAsC,CAAC;AACtE,OAAO,EACL,eAAe,EACf,eAAe,GAChB,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAAE,yBAAyB,EAAE,MAAM,4CAA4C,CAAC;AAEvF;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB;IAIpC,OAAO,MAAM,CAAC,MAAM,CAA+C;QACjE,eAAe,CAAC,KAA8B,EAAE,IAAa,EAAE,WAAoB;YACjF,MAAM,OAAO,GAAI,IAAsD,EAAE,IAAI,IAAI,EAAE,CAAC;YACpF,MAAM,EAAE,iBAAiB,EAAE,GAAG,yBAAyB,CAAC,WAAW,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;YACtF,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,kBAAkB,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;QAClE,CAAC;QACD,OAAO,CAAC,IAA6B,EAAE,IAAa,EAAE,GAAkC;YACtF,OAAO,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;QACzC,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB;IAIpC,OAAO,MAAM,CAAC,MAAM,CAA+C;QACjE,eAAe,CAAC,KAA8B,EAAE,IAAa,EAAE,WAAoB;YACjF,MAAM,OAAO,GAAI,IAAyD,EAAE,OAAO,IAAI,MAAM,CAAC;YAC9F,MAAM,EAAE,QAAQ,EAAE,GAAG,6BAA6B,CAAC,WAAW,CAAC,CAAC;YAChE,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,kBAAkB,CAAC,2BAA2B,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7F,CAAC;QACD,OAAO,CAAC,IAA6B,EAAE,IAAa,EAAE,GAAkC;YACtF,OAAO,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;QAC1C,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB;IAIpC,OAAO,MAAM,CAAC,MAAM,CAA+C;QACjE,eAAe,CAAC,KAA8B,EAAE,IAAa,EAAE,WAAoB;YACjF,MAAM,IAAI,GAAI,IAAsD,EAAE,IAAI,IAAI,MAAM,CAAC;YACrF,MAAM,EAAE,QAAQ,EAAE,GAAG,6BAA6B,CAAC,WAAW,CAAC,CAAC;YAChE,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,kBAAkB,CAAC,2BAA2B,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1F,CAAC;QACD,OAAO,CAAC,IAA6B,EAAE,IAAa,EAAE,GAAkC;YACtF,OAAO,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;QAC1C,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/executors/fs-source-executors.d.ts

@@ -0,0 +1,31 @@
+import type { FsGlobSourceNode, FsTextSourceNode, ResolutionContext, ResolvedSourceArtifact } from '@paraharness/core';
+/**
+ * Loads UTF-8 text and computes a SHA-256 hex digest for an `FsTextSourceNode` (`fs:text-source`).
+ *
+ * Resolves `node.path` against the immutable host repository root when `ctx.scopeHandle` is
+ * omitted, or against `ctx.scopeHandle.worktreePath` when computing in-run grounding diffs (`SPEC.md` §4.3).
+ *
+ * @param {FsTextSourceNode}  node   - Passive text source AST node.
+ * @param {void}              _input - Unused source executor input parameter.
+ * @param {ResolutionContext} ctx    - Source resolution context with optional `scopeHandle`.
+ *
+ * @returns {Promise<ResolvedSourceArtifact<string>>} UTF-8 file text paired with its SHA-256 digest.
+ */
+export declare function executeFsTextSource(node: FsTextSourceNode, _input: void, ctx: ResolutionContext): Promise<ResolvedSourceArtifact<string>>;
+/**
+ * Loads all UTF-8 files matching `node.pattern` in lexicographical order for an `FsGlobSourceNode` (`fs:glob-source`).
+ *
+ * Resolves against the host repository root when `ctx.scopeHandle` is omitted, or against
+ * `ctx.scopeHandle.worktreePath` when computing in-run grounding diffs (`SPEC.md` §4.3).
+ *
+ * @param {FsGlobSourceNode}  node   - Passive glob source AST node.
+ * @param {void}              _input - Unused source executor input parameter.
+ * @param {ResolutionContext} ctx    - Source resolution context with optional `scopeHandle`.
+ *
+ * @returns {Promise<ResolvedSourceArtifact<ReadonlyArray<{ readonly path: string; readonly content: string }>>>} Matched `{ path, content }` records paired with their combined SHA-256 digest.
+ */
+export declare function executeFsGlobSource(node: FsGlobSourceNode, _input: void, ctx: ResolutionContext): Promise<ResolvedSourceArtifact<ReadonlyArray<{
+    readonly path: string;
+    readonly content: string;
+}>>>;
+//# sourceMappingURL=fs-source-executors.d.ts.map

package/dist/executors/fs-source-executors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-source-executors.d.ts","sourceRoot":"","sources":["../../src/executors/fs-source-executors.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,sBAAsB,EACvB,MAAM,mBAAmB,CAAC;AAK3B;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,gBAAgB,EACtB,MAAM,EAAE,IAAI,EACZ,GAAG,EAAE,iBAAiB,GACrB,OAAO,CAAC,sBAAsB,CAAC,MAAM,CAAC,CAAC,CAQzC;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,gBAAgB,EACtB,MAAM,EAAE,IAAI,EACZ,GAAG,EAAE,iBAAiB,GACrB,OAAO,CACR,sBAAsB,CAAC,aAAa,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAC3F,CAeA"}