Interface: FsNamespace

Defined in: fs/src/builders/fs-namespace-contract.ts:41

Declarative builder namespace (fs.*) for @paraharness/fs sources, partition maps, guards, tools, and stores.

Every method returns a passive, frozen AST node or serializable LeaseDelta / ScopePredicate with zero import-time or declaration-time filesystem I/O.

Methods

allowOnly()

allowOnly(globs): FsAllowOnlyGuardNode;

Defined in: fs/src/builders/fs-namespace-contract.ts:134

Compiles a passive FsAllowOnlyGuardNode restricting writes strictly to globs.

Blocks any write path outside globs unless covered by an active lease.

Parameters

Parameter	Type	Description
globs	readonly string[]	Allowed write glob patterns.

Returns

FsAllowOnlyGuardNode

Frozen FsAllowOnlyGuardNode descriptor.

---

allowWriteGlobs()

allowWriteGlobs(globs): LeaseDelta;

Defined in: fs/src/builders/fs-namespace-contract.ts:168

Creates a serializable LeaseDelta unlocking write access to globs.

Matches both exact normalized file paths (including bracketed paths) and POSIX globs.

Parameters

Parameter	Type	Description
globs	readonly string[]	Exact file paths or glob patterns to unlock.

Returns

LeaseDelta

Frozen LeaseDelta record.

---

boundaryGuard()

boundaryGuard<TPartition>(partitionMap): FsBoundaryGuardNode;

Defined in: fs/src/builders/fs-namespace-contract.ts:101

Compiles a passive FsBoundaryGuardNode blocking unleased writes to partition boundaryGlobs.

Projects violatedEffects strictly to the violating boundary file paths.

Type Parameters

Type Parameter	Default type	Description
TPartition extends string	string	Literal union of partition identifiers in partitionMap.

Parameters

Parameter	Type	Description
partitionMap	FsPartitionMapNode<TPartition>	Filesystem partition map AST node.

Returns

FsBoundaryGuardNode

Frozen FsBoundaryGuardNode descriptor.

---

codingTools()

codingTools<THandle>(runner?): readonly [FsReadToolNode<THandle>, FsEditToolNode<THandle>, FsWriteToolNode<THandle>, FsGlobToolNode<THandle>, FsGrepToolNode<THandle>];

Defined in: fs/src/builders/fs-namespace-contract.ts:193

Compiles the 5-tool workspace-jailed coding bundle (read_file, edit_file, write_file, glob_files, grep_files).

Enforces realpath symlink jailing and node_modules write denial at runtime.

Type Parameters

Type Parameter	Default type	Description
THandle	unknown	Runtime handle type of the active isolation scope.

Parameters

Parameter	Type	Description
runner?	MaybeBuilder<NodeRunnerNode>	Optional runner pool AST node or builder (defaults to DEFAULT_NODE_RUNNER_AST_NODE).

Returns

readonly [FsReadToolNode<THandle>, FsEditToolNode<THandle>, FsWriteToolNode<THandle>, FsGlobToolNode<THandle>, FsGrepToolNode<THandle>]

Frozen 5-tuple of coding tools.

---

glob()

glob(globPattern): FsGlobSourceNode;

Defined in: fs/src/builders/fs-namespace-contract.ts:57

Compiles a passive FsGlobSourceNode loading all UTF-8 files matching globPattern.

Resolves matching files in deterministic lexicographical order with a SHA-256 digest.

Parameters

Parameter	Type	Description
globPattern	string	POSIX glob pattern matched against the repository root.

Returns

FsGlobSourceNode

Frozen FsGlobSourceNode descriptor.

---

inPartition()

inPartition<TPartition>(partitionMap, partitionId): object;

Defined in: fs/src/builders/fs-namespace-contract.ts:89

Builds a ScopePredicate scoping rules or skills to partitionId in partitionMap.

Combines Turn-0 partitions: [partitionId] with reactive 'any'-mode effects matching.

Type Parameters

Type Parameter	Default type	Description
TPartition extends string	string	Literal union of partition identifiers in partitionMap.

Parameters

Parameter	Type	Description
partitionMap	FsPartitionMapNode<TPartition>	Filesystem partition map AST node.
partitionId	TPartition	Target partition identifier.

Returns

object

Frozen ScopePredicate record.

Name	Type	Defined in
effects?	FsGlobMatcherNode	core/dist/schemas/core-rules.schema.d.ts:7
partitions	string[]	core/dist/schemas/core-rules.schema.d.ts:6

---

jsonlLessonStore()

jsonlLessonStore(options?): FsJsonlLessonStoreNode;

Defined in: fs/src/builders/fs-namespace-contract.ts:237

Compiles a passive FsJsonlLessonStoreNode configuring the crash-safe hybrid lesson store.

Resolves definitionsDir, statsPath, and lockFile against the immutable host repository root.

Parameters

Parameter	Type	Description
options?	FsJsonlLessonStoreOptions	Optional lesson store host-root path options.

Returns

FsJsonlLessonStoreNode

Frozen FsJsonlLessonStoreNode descriptor.

---

matchGlobs()

matchGlobs(globs, mode?): FsGlobMatcherNode;

Defined in: fs/src/builders/fs-namespace-contract.ts:66

Compiles a passive FsGlobMatcherNode matching FsToolEffect paths against globs.

Matches both exact normalized file paths and POSIX glob patterns.

Parameters

Parameter	Type	Description
globs	readonly string[]	Glob patterns or exact file paths.
mode?	"read" | "write" | "any"	Access mode filter.

Returns

FsGlobMatcherNode

Frozen FsGlobMatcherNode descriptor.

---

maxFilesMutated()

maxFilesMutated(count): FsQuotaTripwireNode;

Defined in: fs/src/builders/fs-namespace-contract.ts:184

Compiles a passive FsQuotaTripwireNode tripping when distinct mutated files exceed count.

Evaluated post-flight after each allowed tool call via RuntimeExecutorRegistry.quotaTripwires.

Parameters

Parameter	Type	Description
count	number	Maximum distinct mutated files allowed.

Returns

FsQuotaTripwireNode

Frozen FsQuotaTripwireNode descriptor.

---

partitionMap()

partitionMap<TPartition>(topology, mapping): FsPartitionMapNode<TPartition>;

Defined in: fs/src/builders/fs-namespace-contract.ts:76

Compiles a passive FsPartitionMapNode mapping logical topology partitions to file globs.

Binds each partition to its implementation globs and public boundaryGlobs.

Type Parameters

Type Parameter	Default type	Description
TPartition extends string	string	Literal union of partition identifiers in topology.

Parameters

Parameter	Type	Description
topology	MaybeBuilder<TopologyNode<TPartition>>	Relational topology AST node or builder.
mapping	Readonly<Record<TPartition, FsPartitionPathMapping>>	Per-partition glob mapping.

Returns

FsPartitionMapNode<TPartition>

Frozen FsPartitionMapNode descriptor.

---

protect()

protect(globs): FsProtectGuardNode;

Defined in: fs/src/builders/fs-namespace-contract.ts:119

Compiles a passive FsProtectGuardNode protecting globs from unleased write mutations.

Projects violatedEffects strictly to the protected paths touched by a write effect.

Parameters

Parameter	Type	Description
globs	readonly string[]	Protected file glob patterns.

Returns

FsProtectGuardNode

Frozen FsProtectGuardNode descriptor.

---

readOnly()

readOnly(): FsReadOnlyGuardNode;

Defined in: fs/src/builders/fs-namespace-contract.ts:126

Compiles a passive FsReadOnlyGuardNode rejecting all unleased filesystem write mutations.

Enforces read-only access across declared and post-flight-diffed tools.

Returns

FsReadOnlyGuardNode

Frozen FsReadOnlyGuardNode descriptor.

---

readOnlyTools()

readOnlyTools<THandle>(runner?): readonly [FsReadToolNode<THandle>, FsGlobToolNode<THandle>, FsGrepToolNode<THandle>];

Defined in: fs/src/builders/fs-namespace-contract.ts:210

Compiles the 3-tool workspace-jailed read-only bundle (read_file, glob_files, grep_files).

Emits read-only FsToolEffect records with mutatesScope: false.

Type Parameters

Type Parameter	Default type	Description
THandle	unknown	Runtime handle type of the active isolation scope.

Parameters

Parameter	Type	Description
runner?	MaybeBuilder<NodeRunnerNode>	Optional runner pool AST node or builder (defaults to DEFAULT_NODE_RUNNER_AST_NODE).

Returns

readonly [FsReadToolNode<THandle>, FsGlobToolNode<THandle>, FsGrepToolNode<THandle>]

Frozen 3-tuple of read-only tools.

---

regexCheck()

regexCheck<THandle>(id, options): FsRegexCheckNode<THandle>;

Defined in: fs/src/builders/fs-namespace-contract.ts:229

Compiles a passive FsRegexCheckNode scanning mutated files matching options.targetGlobs.

Evaluates options.forbidPattern strictly over files mutated during the session or since baseRef.

Type Parameters

Type Parameter	Default type	Description
THandle	unknown	Runtime handle type of the active isolation scope.

Parameters

Parameter	Type	Description
id	string	Unique check identifier.
options	FsRegexCheckOptions	Regex check options.

Returns

FsRegexCheckNode<THandle>

Frozen FsRegexCheckNode descriptor.

---

requireReadBeforeWrite()

requireReadBeforeWrite(): FsRequireReadBeforeWriteGuardNode;

Defined in: fs/src/builders/fs-namespace-contract.ts:141

Compiles a passive FsRequireReadBeforeWriteGuardNode requiring existing files to be read before mutation.

Verifies that any target file existing at baseRef was previously read in observedEffects.

Returns

FsRequireReadBeforeWriteGuardNode

Frozen FsRequireReadBeforeWriteGuardNode descriptor.

---

scopedWrite()

scopedWrite<TPartition>(partitionMap): FsScopedWriteGuardNode;

Defined in: fs/src/builders/fs-namespace-contract.ts:150

Compiles a passive FsScopedWriteGuardNode restricting writes to ctx.activePartitions.

Rejects write mutations outside the member globs of the actor's active partitions.

Type Parameters

Type Parameter	Default type	Description
TPartition extends string	string	Literal union of partition identifiers in partitionMap.

Parameters

Parameter	Type	Description
partitionMap	FsPartitionMapNode<TPartition>	Filesystem partition map AST node.

Returns

FsScopedWriteGuardNode

Frozen FsScopedWriteGuardNode descriptor.

---

secretLiterals()

secretLiterals(patterns?): FsSecretLiteralsGuardNode;

Defined in: fs/src/builders/fs-namespace-contract.ts:160

Compiles a passive FsSecretLiteralsGuardNode scanning proposed file writes for secret literals.

Evaluates built-in high-entropy credential patterns plus optional custom regex patterns.

Parameters

Parameter	Type	Description
patterns?	readonly string[]	Optional custom secret regex pattern strings.

Returns

FsSecretLiteralsGuardNode

Frozen FsSecretLiteralsGuardNode descriptor.

---

telemetry()

telemetry(): FsTelemetryCollectorNode;

Defined in: fs/src/builders/fs-namespace-contract.ts:219

Compiles a passive FsTelemetryCollectorNode collecting filesRead and filesMutated.

Folds observed FsToolEffect records into UniversalStepTelemetry.custom.

Returns

FsTelemetryCollectorNode

Frozen FsTelemetryCollectorNode descriptor.

---

text()

text(filePath): FsTextSourceNode;

Defined in: fs/src/builders/fs-namespace-contract.ts:49

Compiles a passive FsTextSourceNode loading UTF-8 text from filePath.

Resolves against the host repository root or active ResolutionContext.scopeHandle.

Parameters

Parameter	Type	Description
filePath	string	Repository-relative path to the UTF-8 file.

Returns

FsTextSourceNode

Frozen FsTextSourceNode descriptor.

---

violatedPaths()

violatedPaths(violation): string[];

Defined in: fs/src/builders/fs-namespace-contract.ts:176

Extracts deduplicated filesystem paths in first-seen order from violation.violatedEffects.

Inspects 'fs:effect' records in violation.violatedEffects and returns unique string path entries.

Parameters

Parameter	Type	Description
violation	PolicyViolation	Policy violation emitted by a pre-flight or post-flight guard.

Returns

string[]

Deduplicated array of violated filesystem paths in first-seen order.

---

writeGuard()

writeGuard(options): FsWriteGuardNode;

Defined in: fs/src/builders/fs-namespace-contract.ts:111

Compiles a passive FsWriteGuardNode enforcing glob-based write allow/deny rules.

Supports onlyExistingAtBaseRef: true to block edits to existing files while allowing new files.

Parameters

Parameter	Type	Description
options	FsWriteGuardOptions	Write guard configuration options.

Returns

FsWriteGuardNode

Frozen FsWriteGuardNode descriptor.