# Path Namespaces
URL: /runtime/concepts/path-namespaces



A **runtime path** identifies a file within the filesystem capability supplied to one runtime client. It is a canonical POSIX path relative to that capability -- `main.ts`, `models/main.ts`, or `''` for the capability root -- and never has a leading slash. That one definition lets consumers, plugin authors, and host integrators name the same file without exposing the host's storage layout.

## Consumer Source Paths [#consumer-source-paths]

For a filesystem-backed source, `source.path` accepts one canonical root-relative path. The client validates that form before the request reaches a kernel:

```typescript
import { createRuntimeClient } from '@taucad/runtime';
import { fromMemoryFs } from '@taucad/runtime/filesystem';
import { defineRuntime } from '@taucad/runtime/worker';
import { replicad } from '@taucad/replicad';
import { inProcessTransport } from '@taucad/runtime/transport/in-process';

const runtime = defineRuntime({ plugins: [replicad()] });
const client = createRuntimeClient({
  transport: inProcessTransport({ runtime, fileSystem: fromMemoryFs() }),
});

const document = client.open({ source: { path: 'models/main.ts' } });
await document.evaluation();
document.close();
await client.shutdown();
```

For inline source, `source.entry` is a key in `source.files` and may include directory segments:

```typescript
import { createRuntimeClient } from '@taucad/runtime';
import { fromMemoryFs } from '@taucad/runtime/filesystem';
import { defineRuntime } from '@taucad/runtime/worker';
import { replicad } from '@taucad/replicad';
import { inProcessTransport } from '@taucad/runtime/transport/in-process';

const runtime = defineRuntime({ plugins: [replicad()] });
const client = createRuntimeClient({
  transport: inProcessTransport({ runtime, fileSystem: fromMemoryFs() }),
});
const mainSource = 'export default () => null;';
const partSource = 'export const part = null;';

const document = client.open({
  source: {
    files: {
      'models/main.ts': mainSource,
      'lib/part.ts': partSource,
    },
    entry: 'models/main.ts',
  },
});
await document.evaluation();
document.close();
await client.shutdown();
```

## Plugin Entry and Dependency Paths [#plugin-entry-and-dependency-paths]

Kernel and bundler methods receive the canonical `entryPath` that names the model's evaluation root within the supplied runtime filesystem:

```typescript
import type { ResolveInput, ResolveOutput, KernelServices } from '@taucad/runtime/types';

export async function resolve(
  { entryPath }: ResolveInput,
  { filesystem }: Pick<KernelServices, 'filesystem'>,
): Promise<ResolveOutput> {
  const source = await filesystem.readFile(entryPath, 'utf8');
  return { resolved: [entryPath, 'lib/part.ts'], unresolved: source ? [] : [entryPath] };
}
```

Middleware receives the same normalized `entryPath`. Dependency `path` values and all `KernelFileSystem` arguments use this namespace too: `entryPath` is the evaluation root, `path` is any dependency.

## Host Filesystem Roots [#host-filesystem-roots]

Filesystem adapters decide which host resource becomes the capability root:

| Adapter                          | Host-owned input                    | Runtime view                                      |
| -------------------------------- | ----------------------------------- | ------------------------------------------------- |
| `fromNodeFs('/srv/cad/widget')`  | A host OS directory                 | `main.ts` maps to `/srv/cad/widget/main.ts`       |
| `fromBrowserFs(directoryHandle)` | A browser directory handle          | `main.ts` is relative to that handle              |
| `fromFileSystemBridge(open)`     | A bridge already rooted by the host | `main.ts` is relative to the selected bridge root |
| `fromFsLike(fs)`                 | An already-confined filesystem      | `main.ts` is resolved by that confined filesystem |
| `fromMemoryFs(files)`            | An in-memory file map               | Map keys are exposed as runtime paths             |

The adapter or host chooses the boundary. Kernels, bundlers, and middleware receive runtime paths only -- never host OS paths, project IDs, or authority-global mount paths.

## Related Path Names [#related-path-names]

Other Tau layers deliberately use different namespaces:

| Name                         | Meaning                                                                   |
| ---------------------------- | ------------------------------------------------------------------------- |
| Project manifest `entryPath` | Canonical project-root-relative entry path                                |
| Runtime `source.path`        | Canonical capability-root-relative consumer input                         |
| Plugin `entryPath`           | Canonical capability-root-relative evaluation entry                       |
| Dependency `path`            | Canonical capability-root-relative path for any dependency                |
| Authority-global path        | Host-owned route such as `/projects/widget/main.ts`; never a plugin input |
| Host path                    | Native OS path used only at an adapter boundary                           |

Keep each namespace at its owning boundary. In particular, do not pass `/projects/<id>/...` or a host OS path to a kernel to recreate access checks the filesystem adapter already owns.

## Further Reading [#further-reading]

* [Architecture](/runtime/concepts/architecture) -- where filesystem adapters and plugins sit
* [Filesystem API](/runtime/api/filesystem) -- constructors that establish a runtime filesystem root
* [Custom Kernel](/runtime/guides/custom-kernel) -- consuming `entryPath` and returning dependencies
* [Embedding in a Host](/runtime/guides/embedding-in-a-host) -- rooting a runtime in a host-owned filesystem