@aigne/aos 0.2.0-beta

package/dist/session/session-user-afs.d.cts

@@ -0,0 +1,296 @@
+import { SettingsSchemaHandle } from "./settings-schema-store.cjs";
+import * as _aigne_afs0 from "@aigne/afs";
+import { AFSBatchDeleteEntry, AFSBatchDeleteResult, AFSBatchReadEntry, AFSBatchReadResult, AFSBatchWriteEntry, AFSBatchWriteResult, AFSCollectionQueryResult, AFSCollectionQuerySpec, AFSDeleteOptions, AFSDeleteResult, AFSEventCallback, AFSEventFilter, AFSExecOptions, AFSExecResult, AFSExplainOptions, AFSExplainResult, AFSListOptions, AFSListResult, AFSModule, AFSQueryOptions, AFSReadOptions, AFSReadResult, AFSRoot, AFSSearchOptions, AFSSearchResult, AFSStatOptions, AFSStatResult, AFSUnsubscribe, AFSWriteEntryPayload, AFSWriteOptions, AFSWriteResult, MountInfo } from "@aigne/afs";
+
+//#region src/session/session-user-afs.d.ts
+/**
+ * STATIC full set of overlay prefixes a SessionUserAFS may mount — the
+ * anonymous-bearer denylist for signed raw URLs (afs-preview design §3).
+ *
+ * Deliberately NOT derived from an instance's `overlays` array: `/space` and
+ * `/instance/settings` are conditionally mounted, so per-instance derivation
+ * would drift with wiring. Fail-closed: an anonymous raw URL is refused for
+ * these prefixes even when the issuing session didn't mount them.
+ *
+ * KEEP IN SYNC with the constructor below — the unit test enumerates this
+ * set against the constructor's possible mounts, table-driven.
+ */
+declare const SESSION_OVERLAY_PREFIXES: readonly ["/user/index", "/user", "/tmp", "/space", "/instance/settings"];
+/**
+ * Whether a (sanitized) path falls under any session-private overlay prefix.
+ * Used by the raw-URL primitives to refuse anonymous bearer URLs for
+ * session-private content (issue-side denial + verify-side second defense).
+ */
+declare function isSessionPrivatePath(path: string): boolean;
+/**
+ * Guard the first-match-by-prefix invariant: no overlay may be preceded by
+ * another whose prefix is a proper prefix of it (which would swallow its
+ * paths). `/instance/settings` MUST come before any future `/instance` or `/`
+ * overlay. Extracted + exported so the ordering contract is unit-testable
+ * without reaching into the class. Throws on violation (a wiring bug).
+ */
+declare function assertOverlayOrder(prefixes: string[]): void;
+declare class SessionUserAFS implements AFSRoot {
+  private readonly base;
+  /**
+   * True when the blocklet manifest declares `index:` and `/user` search is
+   * expected to be served by `/user/index`. Kept separate from the
+   * `/user/index` overlay itself because runtimes reserve that path with a
+   * null provider even for no-index blocklets to make direct `/user/index`
+   * access fail closed.
+   */
+  private readonly indexSearchRequired;
+  readonly name: string;
+  readonly accessMode: AFSRoot["accessMode"];
+  private readonly overlays;
+  /**
+   * Named reference to the settings resolver overlay (the overlay table only
+   * stores it anonymously) so `beginRender`/`endRender` can proxy to it —
+   * settings-layering §2.B render boundary.
+   */
+  private readonly settingsResolver;
+  constructor(base: AFSRoot, /** The caller's per-user provider (userDataBackend output), or null for anonymous. */
+
+  userProvider: AFSModule | null, /** The session's `/tmp` provider (joinSession's sessionTmpBackend output), or null. */
+
+  tmpProvider: AFSModule | null, sessionId: string,
+  /**
+   * The per-session SettingsResolver intercepting `/instance/settings/**`
+   * (instance+user settings cascade), or null when settings aren't wired.
+   */
+
+  settingsResolver?: AFSModule | null,
+  /**
+   * The caller's whole DID Space root provider. Omit to leave `/space`
+   * untouched; pass null to explicitly reserve `/space` and fail closed.
+   */
+  spaceProvider?: AFSModule | null,
+  /**
+   * The caller's per-user semantic index (`@aigne/afs-index`) at `/user/index`.
+   * Omit to leave `/user/index` untouched (falls through to the `/user`
+   * provider); pass null to reserve it and fail closed. Mounted BEFORE `/user`
+   * so child-first routing sends `/user/index/**` here, mirroring how
+   * `/instance/settings` precedes `/instance`.
+   */
+  indexProvider?: AFSModule | null,
+  /**
+   * Replicated-collection overlays built by createSessionView when the blocklet
+   * manifest declares `replicated` collections. Each entry is mounted at its
+   * `prefix` (e.g. `/instance`) AFTER the `/instance/settings` interceptor so
+   * child-first routing sends `/instance/settings/**` to the SettingsResolver
+   * and everything else in the prefix to the ReplicationResolver.
+   */
+  replicationOverlays?: Array<{
+    prefix: string;
+    id: string;
+    provider: AFSModule | null;
+  }>,
+  /**
+   * True when the blocklet manifest declares `index:` and `/user` search is
+   * expected to be served by `/user/index`. Kept separate from the
+   * `/user/index` overlay itself because runtimes reserve that path with a
+   * null provider even for no-index blocklets to make direct `/user/index`
+   * access fail closed.
+   */
+  indexSearchRequired?: boolean);
+  /** Match a path against the overlay table. Returns the overlay + sub-path. */
+  private matchOverlay;
+  /** Overlays that are actually backed (provider present). */
+  private get activeOverlays();
+  /** Backed AND root-level overlays — the ones surfaced at `/` / in getMounts. */
+  private get rootOverlays();
+  private rejectMissing;
+  /**
+   * Whether a write context originates from an untrusted network client.
+   * `callerOrigin` is a host-stamped, unforgeable marker (strip + trusted reset,
+   * see FORGEABLE_CONTEXT_FIELDS); internal code (seeding / cron / agent /
+   * operator CLI) carries no `callerOrigin`. Mirrors the reflexive effect gate's
+   * network check (`exec-effect-gate.ts`).
+   */
+  private isNetworkOrigin;
+  /**
+   * Caller-origin base-write gate (instance-write-authz §5.1). A network client
+   * may never bare-write a BASE-fallthrough path — any path NOT matched by an
+   * overlay (`/instance/<non-mediated>`, `/packages`, `/dev`, `/registry`, `/`).
+   * Authorized `/instance` writes must go through a resolver overlay
+   * (`/instance/settings` → SettingsResolver, future `/instance/app` →
+   * ReplicationResolver — each carries its own role/minRole gate) or internal
+   * trusted code (`callerOrigin: undefined`).
+   *
+   * Called ONLY on the base-fallthrough branch (overlay-matched paths never
+   * reach here). STRICTER than the effect gate: it rejects AUTHENTICATED network
+   * callers too (the effect gate lets `caller.did` through) — that authed-but-
+   * network reflexive base write is exactly Finding 1's live path.
+   */
+  private forbiddenBaseWrite;
+  private enforceBaseWriteGate;
+  /** Re-prefix a provider-relative path back into the overlay namespace. */
+  private reprefix;
+  list(path: string, options?: AFSListOptions): Promise<AFSListResult>;
+  read(path: string, options?: AFSReadOptions): Promise<AFSReadResult>;
+  /**
+   * Overlay-dispatch for `presignRead` (preview-r2-direct §5a.2 / T1.2). Same
+   * routing as `read`: a matched overlay whose provider implements `presignRead`
+   * gets the sub-path; a base-fallthrough path (or an overlay provider without
+   * the capability) → `null` (fail-soft → the raw handler serves bytes itself).
+   *
+   * The meta-only ACL and the `null`-on-everything fail-soft live DEEPER (the
+   * `/user` overlay provider is a `ProjectionProvider` → core `AFS` (globalAFS),
+   * where the authoritative meta guard runs — §5a.2 "routing to the root
+   * computation"); this layer only forwards.
+   *
+   * This is the HANDLER-FACING surface (`scoped.afs`), so it owns the §5a.5
+   * "NEVER throws to the handler" guarantee end-to-end: a deeper layer that
+   * throws (e.g. a read-disabled `ProjectionProvider.checkOp("read")` →
+   * `AFSAccessModeError`) is caught here → `null` → the raw handler serves bytes
+   * itself (and the worker-serve read then re-applies that same gate). No URL
+   * can leak past a read-disabled / failing projection.
+   */
+  presignRead(path: string, opts?: {
+    responseContentType?: string;
+  }): Promise<{
+    url: string;
+    expiresAt: string;
+  } | null>;
+  write(path: string, content: AFSWriteEntryPayload, options?: AFSWriteOptions): Promise<AFSWriteResult>;
+  delete(path: string, options?: AFSDeleteOptions): Promise<AFSDeleteResult>;
+  /** Plan contiguous runs of entry indices by overlay identity (null = base). */
+  private planOverlayRuns;
+  batchWrite(entries: AFSBatchWriteEntry[], options?: _aigne_afs0.AFSOperationOptions): Promise<AFSBatchWriteResult>;
+  batchDelete(entries: AFSBatchDeleteEntry[], options?: _aigne_afs0.AFSOperationOptions): Promise<AFSBatchDeleteResult>;
+  batchRead(entries: AFSBatchReadEntry[], options?: _aigne_afs0.AFSOperationOptions): Promise<AFSBatchReadResult>;
+  query(path: string, spec: AFSCollectionQuerySpec, options?: AFSQueryOptions): Promise<AFSCollectionQueryResult>;
+  stat(path: string, options?: AFSStatOptions): Promise<AFSStatResult>;
+  explain(path: string, options?: AFSExplainOptions): Promise<AFSExplainResult>;
+  /**
+   * Find the `/user/index` overlay's backing provider, or undefined when
+   * unmounted (no `index:` manifest section) OR reserved-null (blocklet
+   * declares `index:` but this caller has no DID / no callerDid — see
+   * `createSessionView`'s `indexProvider` doc).
+   */
+  private findIndexOverlay;
+  private isAfsValidationError;
+  private isAfsDependencyError;
+  private searchDiagnostics;
+  private rejectIndexSearchFallback;
+  /**
+   * Parse a `read()`-returned raw content string as JSON, matching the exact
+   * fail-soft convention `IndexFollower.indexEntry` uses when hydrating
+   * changelog rows (`providers/basic/index/src/follower.ts`): non-string
+   * content is passed through untouched; a string that isn't valid JSON is
+   * kept as the raw string rather than dropped. afs-list's `performSearch`
+   * (P5 forward contract) expects a resolved `content` object for JSON
+   * entries — this is what makes that true without a second copy of the
+   * parse-or-passthrough logic living in the hydration loop below.
+   */
+  private parseEntryContent;
+  /**
+   * Hydrate index-query hits (`{ entryPath, score, matchType }` — path only,
+   * no content) into full `AFSEntry` objects by reading each `entryPath`
+   * through THIS session view (so the caller's own `/user` overlay + its
+   * per-caller isolation applies a second time, on top of the index query's
+   * own `boundDomains` isolation — belt-and-suspenders, not redundant: see
+   * design.md P5 section). A stale entry (index has it, storage doesn't —
+   * e.g. a delete that hasn't reached the follower yet) fails the `read()`
+   * and is skipped rather than surfaced as a broken result.
+   */
+  private hydrateSearchEntries;
+  /**
+   * Search-verb forward contract (P5, design.md "search verb forwarding"):
+   * a `/user/**` search first tries the caller's semantic `/user/index`
+   * (when mounted with a real provider), scoping hits to the requested
+   * subtree and hydrating them with real content via `read()`. For blocklets
+   * whose manifest declares `index:`, the index is authoritative: failures are
+   * surfaced and DID Space native search is refused because it is an O(N)
+   * content scan. Legacy/no-index blocklets keep the old direct overlay search
+   * behavior. A successful empty index result is authoritative and returns an
+   * empty array. Index results and fallback results are never unioned. Any other
+   * overlay (`/user/index` addressed directly, `/tmp`, `/space`,
+   * `/instance/settings`, replication overlays) keeps its pre-existing
+   * single-overlay-search behavior unchanged.
+   */
+  search(path: string, query: string, options?: AFSSearchOptions): Promise<AFSSearchResult>;
+  exec(path: string, args: Record<string, unknown>, options: AFSExecOptions): Promise<AFSExecResult>;
+  /**
+   * Inject `context.afs = this` so downstream provider handlers that call
+   * back into AFS (`ctx.context.afs.read`/`.write`/`.exec`/...) hit this
+   * overlaid session view — not the bare runtime root the provider was
+   * mounted into. Without this, the `/user` overlay (and any other per-
+   * caller overlay) is invisible to handler-internal AFS calls, so writes
+   * silently land on the global `/user` fs mount instead of the caller's
+   * DID-Space-projected `/user`.
+   */
+  private withSelfContext;
+  subscribe(filter: AFSEventFilter, callback: AFSEventCallback): AFSUnsubscribe;
+  /**
+   * Subscribe one overlay's backing provider, re-prefixing bridged event paths
+   * back into the overlay namespace. No-op when the overlay is unbacked
+   * (anonymous `/user`) or its provider lacks `subscribe`.
+   */
+  private subscribeOverlay;
+  beginRender(renderId: string): Promise<void>;
+  endRender(renderId: string): void;
+  getMounts(namespace?: string | null): MountInfo[];
+  initializePhysicalPath(...args: Parameters<AFSRoot["initializePhysicalPath"]>): Promise<string>;
+  cleanupPhysicalPath(...args: Parameters<AFSRoot["cleanupPhysicalPath"]>): Promise<void>;
+  setEventSink(...args: Parameters<NonNullable<AFSModule["setEventSink"]>>): void;
+  setSecretCapability(...args: Parameters<NonNullable<AFSModule["setSecretCapability"]>>): void;
+}
+/**
+ * Assemble a caller's per-session view: a SettingsResolver (instance+user
+ * settings cascade, role-aware) wrapped by a SessionUserAFS (`/user` +
+ * optional `/space` + `/tmp` + `/instance/settings`). This is the construction the daemon's
+ * `buildSessionView` chokepoint delegates to — extracted so the role→resolver
+ * wiring is unit-testable in isolation (the daemon's only remaining job is to
+ * RESOLVE `role` from the verified session before calling this).
+ *
+ * The resolver always exists (even for anonymous / no role) so
+ * `/instance/settings` carries correct capability hints + enforcement for every
+ * caller — there is no bypass path.
+ */
+declare function createSessionView(opts: {
+  base: AFSRoot;
+  userProvider: AFSModule | null;
+  tmpProvider: AFSModule | null;
+  /**
+   * Omitted → no `/space` overlay. null → `/space` reserved and NotFound
+   * (fail-closed). Provider → mounted caller DID Space root.
+   */
+  spaceProvider?: AFSModule | null; /** Caller role from the verified session; undefined → non-admin (fail-closed). */
+  role: string | undefined;
+  sessionId: string;
+  /**
+   * Derived package-schema handle for this blocklet (settings-layering
+   * Phase 1c), pre-bound to identity + base by the runtime. Optional — absent
+   * means no derived index (legacy resolution; existing call sites/tests
+   * unchanged).
+   */
+  settingsSchema?: SettingsSchemaHandle | null;
+  /**
+   * Caller's per-user semantic index provider mounted at `/user/index`.
+   * Omitted → no overlay (path falls through to `/user`); null → reserved.
+   */
+  indexProvider?: AFSModule | null;
+  /**
+   * Whether `/user` search must be served by `/user/index` because the
+   * blocklet manifest declares `index:`. Kept distinct from `indexProvider`
+   * because runtimes may reserve `/user/index` with null for no-index
+   * blocklets while direct path access still fails closed.
+   */
+  indexSearchRequired?: boolean;
+  /**
+   * Verified caller DID (from the session, never client-supplied). Forwarded
+   * to ReplicationResolver for authorship tagging and ownItem delete gate.
+   * null/undefined → anonymous (no copy-side writes).
+   */
+  callerDid?: string | null;
+  /**
+   * Replicated-collection declarations parsed from the blocklet manifest.
+   * When non-empty, a ReplicationResolver is built and mounted at the computed
+   * common ancestor prefix (e.g. "/instance"). null/omitted → no overlay.
+   */
+  replicated?: Record<string, _aigne_afs0.ReplicatedCollection> | null;
+}): SessionUserAFS;
+//#endregion
+export { SESSION_OVERLAY_PREFIXES, SessionUserAFS, assertOverlayOrder, createSessionView, isSessionPrivatePath };
+//# sourceMappingURL=session-user-afs.d.cts.map

package/dist/session/session-user-afs.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-user-afs.d.cts","names":[],"sources":["../../src/session/session-user-afs.ts"],"mappings":";;;;;;;;;;;;;;;;;cAgLa,wBAAA;;;;;;iBAaG,oBAAA,CAAqB,IAAA;;;;;;;;iBAWrB,kBAAA,CAAmB,QAAA;AAAA,cAgDtB,cAAA,YAA0B,OAAA;EAAA,iBAclB,IAAA;EA2iCoD;;;;;;;EAAA,iBApgCpD,mBAAA;EAAA,SApDV,IAAA;EAAA,SACA,UAAA,EAAY,OAAA;EAAA,iBAEJ,QAAA;EAUE;;;;;EAAA,iBAHF,gBAAA;cAGE,IAAA,EAAM,OAAA;;EAEvB,YAAA,EAAc,SAAA,SAFG;;EAIjB,WAAA,EAAa,SAAA,SACb,SAAA;EAHA;;;;;EAQA,gBAAA,GAAkB,SAAA;EAAlB;;;;EAKA,aAAA,GAAgB,SAAA;EAgBM;;;;;;;EARtB,aAAA,GAAgB,SAAA;EA6EN;;;;;;;EArEV,mBAAA,GAAsB,KAAA;IAAQ,MAAA;IAAgB,EAAA;IAAY,QAAA,EAAU,SAAA;EAAA;EA2HV;;;;;;;EAnHzC,mBAAA;EAgLjB;EAAA,QA9HM,YAAA;EA+HN;EAAA,YApHU,cAAA,CAAA;EAqHC;EAAA,YAhHD,YAAA,CAAA;EAAA,QAIJ,aAAA;EA4HN;;;;;;;EAAA,QAjHM,eAAA;EAkIK;;;;;;;;;;;;;;EAAA,QAhHL,kBAAA;EAAA,QAOA,oBAAA;EAqOwB;EAAA,QAhOxB,QAAA;EAIF,IAAA,CAAK,IAAA,UAAc,OAAA,GAAU,cAAA,GAAiB,OAAA,CAAQ,aAAA;EA+BtD,IAAA,CAAK,IAAA,UAAc,OAAA,GAAU,cAAA,GAAiB,OAAA,CAAQ,aAAA;EAkQtD;;;;;;;;;;;;;;;;;;EArOA,WAAA,CACJ,IAAA,UACA,IAAA;IAAS,mBAAA;EAAA,IACR,OAAA;IAAU,GAAA;IAAa,SAAA;EAAA;EAepB,KAAA,CACJ,IAAA,UACA,OAAA,EAAS,oBAAA,EACT,OAAA,GAAU,eAAA,GACT,OAAA,CAAQ,cAAA;EAcL,MAAA,CAAO,IAAA,UAAc,OAAA,GAAU,gBAAA,GAAmB,OAAA,CAAQ,eAAA;EA4QE;EAAA,QAlP1D,eAAA;EAWF,UAAA,CACJ,OAAA,EAAS,kBAAA,IACT,OAAA,GAD2B,WAAA,CACI,mBAAA,GAC9B,OAAA,CAAQ,mBAAA;EAmFL,WAAA,CACJ,OAAA,EAAS,mBAAA,IACT,OAAA,GAD4B,WAAA,CACG,mBAAA,GAC9B,OAAA,CAAQ,oBAAA;EAmEL,SAAA,CACJ,OAAA,EAAS,iBAAA,IACT,OAAA,GAD0B,WAAA,CACK,mBAAA,GAC9B,OAAA,CAAQ,kBAAA;EAoBL,KAAA,CACJ,IAAA,UACA,IAAA,EAAM,sBAAA,EACN,OAAA,GAAU,eAAA,GACT,OAAA,CAAQ,wBAAA;EA+BL,IAAA,CAAK,IAAA,UAAc,OAAA,GAAU,cAAA,GAAiB,OAAA,CAAQ,aAAA;EAiBtD,OAAA,CAAQ,IAAA,UAAc,OAAA,GAAU,iBAAA,GAAoB,OAAA,CAAQ,gBAAA;EA0M5D;;;;;;EAAA,QAtLE,gBAAA;EAAA,QAIA,oBAAA;EAAA,QAKA,oBAAA;EAAA,QAKA,iBAAA;EAAA,QA4BA,yBAAA;EA2SG;;;;;;;;;;EAAA,QA9QH,iBAAA;EA0ZA;;;;;;;;;;EAAA,QAvYM,oBAAA;EAmbkB;;;;;;;;;;;;;;EAvV1B,MAAA,CAAO,IAAA,UAAc,KAAA,UAAe,OAAA,GAAU,gBAAA,GAAmB,OAAA,CAAQ,eAAA;EA4JzE,IAAA,CACJ,IAAA,UACA,IAAA,EAAM,MAAA,mBACN,OAAA,EAAS,cAAA,GACR,OAAA,CAAQ,aAAA;EAmM6B;;;;AAiB1C;;;;;EAjB0C,QApHhC,eAAA;EAeR,SAAA,CAAU,MAAA,EAAQ,cAAA,EAAgB,QAAA,EAAU,gBAAA,GAAmB,cAAA;EA8HtC;;;;;EAAA,QAjFjB,gBAAA;EAiBF,WAAA,CAAY,QAAA,WAAmB,OAAA;EAIrC,SAAA,CAAU,QAAA;EAIV,SAAA,CAAU,SAAA,mBAA4B,SAAA;EAmBtC,sBAAA,CAAA,GAA0B,IAAA,EAAM,UAAA,CAAW,OAAA,8BAAkC,OAAA;EAI7E,mBAAA,CAAA,GAAuB,IAAA,EAAM,UAAA,CAAW,OAAA,2BAA+B,OAAA;EAIvE,YAAA,CAAA,GAAgB,IAAA,EAAM,UAAA,CAAW,WAAA,CAAY,SAAA;EAI7C,mBAAA,CAAA,GAAuB,IAAA,EAAM,UAAA,CAAW,WAAA,CAAY,SAAA;AAAA;;;;;;;;;;;;;iBAiBtC,iBAAA,CAAkB,IAAA;EAChC,IAAA,EAAM,OAAA;EACN,YAAA,EAAc,SAAA;EACd,WAAA,EAAa,SAAA;;;;;EAKb,aAAA,GAAgB,SAAA;EAEhB,IAAA;EACA,SAAA;;;;;;;EAOA,cAAA,GAVyB,oBAAA;;;;;EAezB,aAAA,GAAgB,SAAA;;;;;;;EAOhB,mBAAA;;;;;;EAMA,SAAA;;;;;;EAMA,UAAA,GAAa,MAAA,SAnBY,WAAA,CAmBwB,oBAAA;AAAA,IAC/C,cAAA"}

package/dist/session/session-user-afs.d.mts

@@ -0,0 +1,296 @@
+import { SettingsSchemaHandle } from "./settings-schema-store.mjs";
+import * as _aigne_afs0 from "@aigne/afs";
+import { AFSBatchDeleteEntry, AFSBatchDeleteResult, AFSBatchReadEntry, AFSBatchReadResult, AFSBatchWriteEntry, AFSBatchWriteResult, AFSCollectionQueryResult, AFSCollectionQuerySpec, AFSDeleteOptions, AFSDeleteResult, AFSEventCallback, AFSEventFilter, AFSExecOptions, AFSExecResult, AFSExplainOptions, AFSExplainResult, AFSListOptions, AFSListResult, AFSModule, AFSQueryOptions, AFSReadOptions, AFSReadResult, AFSRoot, AFSSearchOptions, AFSSearchResult, AFSStatOptions, AFSStatResult, AFSUnsubscribe, AFSWriteEntryPayload, AFSWriteOptions, AFSWriteResult, MountInfo } from "@aigne/afs";
+
+//#region src/session/session-user-afs.d.ts
+/**
+ * STATIC full set of overlay prefixes a SessionUserAFS may mount — the
+ * anonymous-bearer denylist for signed raw URLs (afs-preview design §3).
+ *
+ * Deliberately NOT derived from an instance's `overlays` array: `/space` and
+ * `/instance/settings` are conditionally mounted, so per-instance derivation
+ * would drift with wiring. Fail-closed: an anonymous raw URL is refused for
+ * these prefixes even when the issuing session didn't mount them.
+ *
+ * KEEP IN SYNC with the constructor below — the unit test enumerates this
+ * set against the constructor's possible mounts, table-driven.
+ */
+declare const SESSION_OVERLAY_PREFIXES: readonly ["/user/index", "/user", "/tmp", "/space", "/instance/settings"];
+/**
+ * Whether a (sanitized) path falls under any session-private overlay prefix.
+ * Used by the raw-URL primitives to refuse anonymous bearer URLs for
+ * session-private content (issue-side denial + verify-side second defense).
+ */
+declare function isSessionPrivatePath(path: string): boolean;
+/**
+ * Guard the first-match-by-prefix invariant: no overlay may be preceded by
+ * another whose prefix is a proper prefix of it (which would swallow its
+ * paths). `/instance/settings` MUST come before any future `/instance` or `/`
+ * overlay. Extracted + exported so the ordering contract is unit-testable
+ * without reaching into the class. Throws on violation (a wiring bug).
+ */
+declare function assertOverlayOrder(prefixes: string[]): void;
+declare class SessionUserAFS implements AFSRoot {
+  private readonly base;
+  /**
+   * True when the blocklet manifest declares `index:` and `/user` search is
+   * expected to be served by `/user/index`. Kept separate from the
+   * `/user/index` overlay itself because runtimes reserve that path with a
+   * null provider even for no-index blocklets to make direct `/user/index`
+   * access fail closed.
+   */
+  private readonly indexSearchRequired;
+  readonly name: string;
+  readonly accessMode: AFSRoot["accessMode"];
+  private readonly overlays;
+  /**
+   * Named reference to the settings resolver overlay (the overlay table only
+   * stores it anonymously) so `beginRender`/`endRender` can proxy to it —
+   * settings-layering §2.B render boundary.
+   */
+  private readonly settingsResolver;
+  constructor(base: AFSRoot, /** The caller's per-user provider (userDataBackend output), or null for anonymous. */
+
+  userProvider: AFSModule | null, /** The session's `/tmp` provider (joinSession's sessionTmpBackend output), or null. */
+
+  tmpProvider: AFSModule | null, sessionId: string,
+  /**
+   * The per-session SettingsResolver intercepting `/instance/settings/**`
+   * (instance+user settings cascade), or null when settings aren't wired.
+   */
+
+  settingsResolver?: AFSModule | null,
+  /**
+   * The caller's whole DID Space root provider. Omit to leave `/space`
+   * untouched; pass null to explicitly reserve `/space` and fail closed.
+   */
+  spaceProvider?: AFSModule | null,
+  /**
+   * The caller's per-user semantic index (`@aigne/afs-index`) at `/user/index`.
+   * Omit to leave `/user/index` untouched (falls through to the `/user`
+   * provider); pass null to reserve it and fail closed. Mounted BEFORE `/user`
+   * so child-first routing sends `/user/index/**` here, mirroring how
+   * `/instance/settings` precedes `/instance`.
+   */
+  indexProvider?: AFSModule | null,
+  /**
+   * Replicated-collection overlays built by createSessionView when the blocklet
+   * manifest declares `replicated` collections. Each entry is mounted at its
+   * `prefix` (e.g. `/instance`) AFTER the `/instance/settings` interceptor so
+   * child-first routing sends `/instance/settings/**` to the SettingsResolver
+   * and everything else in the prefix to the ReplicationResolver.
+   */
+  replicationOverlays?: Array<{
+    prefix: string;
+    id: string;
+    provider: AFSModule | null;
+  }>,
+  /**
+   * True when the blocklet manifest declares `index:` and `/user` search is
+   * expected to be served by `/user/index`. Kept separate from the
+   * `/user/index` overlay itself because runtimes reserve that path with a
+   * null provider even for no-index blocklets to make direct `/user/index`
+   * access fail closed.
+   */
+  indexSearchRequired?: boolean);
+  /** Match a path against the overlay table. Returns the overlay + sub-path. */
+  private matchOverlay;
+  /** Overlays that are actually backed (provider present). */
+  private get activeOverlays();
+  /** Backed AND root-level overlays — the ones surfaced at `/` / in getMounts. */
+  private get rootOverlays();
+  private rejectMissing;
+  /**
+   * Whether a write context originates from an untrusted network client.
+   * `callerOrigin` is a host-stamped, unforgeable marker (strip + trusted reset,
+   * see FORGEABLE_CONTEXT_FIELDS); internal code (seeding / cron / agent /
+   * operator CLI) carries no `callerOrigin`. Mirrors the reflexive effect gate's
+   * network check (`exec-effect-gate.ts`).
+   */
+  private isNetworkOrigin;
+  /**
+   * Caller-origin base-write gate (instance-write-authz §5.1). A network client
+   * may never bare-write a BASE-fallthrough path — any path NOT matched by an
+   * overlay (`/instance/<non-mediated>`, `/packages`, `/dev`, `/registry`, `/`).
+   * Authorized `/instance` writes must go through a resolver overlay
+   * (`/instance/settings` → SettingsResolver, future `/instance/app` →
+   * ReplicationResolver — each carries its own role/minRole gate) or internal
+   * trusted code (`callerOrigin: undefined`).
+   *
+   * Called ONLY on the base-fallthrough branch (overlay-matched paths never
+   * reach here). STRICTER than the effect gate: it rejects AUTHENTICATED network
+   * callers too (the effect gate lets `caller.did` through) — that authed-but-
+   * network reflexive base write is exactly Finding 1's live path.
+   */
+  private forbiddenBaseWrite;
+  private enforceBaseWriteGate;
+  /** Re-prefix a provider-relative path back into the overlay namespace. */
+  private reprefix;
+  list(path: string, options?: AFSListOptions): Promise<AFSListResult>;
+  read(path: string, options?: AFSReadOptions): Promise<AFSReadResult>;
+  /**
+   * Overlay-dispatch for `presignRead` (preview-r2-direct §5a.2 / T1.2). Same
+   * routing as `read`: a matched overlay whose provider implements `presignRead`
+   * gets the sub-path; a base-fallthrough path (or an overlay provider without
+   * the capability) → `null` (fail-soft → the raw handler serves bytes itself).
+   *
+   * The meta-only ACL and the `null`-on-everything fail-soft live DEEPER (the
+   * `/user` overlay provider is a `ProjectionProvider` → core `AFS` (globalAFS),
+   * where the authoritative meta guard runs — §5a.2 "routing to the root
+   * computation"); this layer only forwards.
+   *
+   * This is the HANDLER-FACING surface (`scoped.afs`), so it owns the §5a.5
+   * "NEVER throws to the handler" guarantee end-to-end: a deeper layer that
+   * throws (e.g. a read-disabled `ProjectionProvider.checkOp("read")` →
+   * `AFSAccessModeError`) is caught here → `null` → the raw handler serves bytes
+   * itself (and the worker-serve read then re-applies that same gate). No URL
+   * can leak past a read-disabled / failing projection.
+   */
+  presignRead(path: string, opts?: {
+    responseContentType?: string;
+  }): Promise<{
+    url: string;
+    expiresAt: string;
+  } | null>;
+  write(path: string, content: AFSWriteEntryPayload, options?: AFSWriteOptions): Promise<AFSWriteResult>;
+  delete(path: string, options?: AFSDeleteOptions): Promise<AFSDeleteResult>;
+  /** Plan contiguous runs of entry indices by overlay identity (null = base). */
+  private planOverlayRuns;
+  batchWrite(entries: AFSBatchWriteEntry[], options?: _aigne_afs0.AFSOperationOptions): Promise<AFSBatchWriteResult>;
+  batchDelete(entries: AFSBatchDeleteEntry[], options?: _aigne_afs0.AFSOperationOptions): Promise<AFSBatchDeleteResult>;
+  batchRead(entries: AFSBatchReadEntry[], options?: _aigne_afs0.AFSOperationOptions): Promise<AFSBatchReadResult>;
+  query(path: string, spec: AFSCollectionQuerySpec, options?: AFSQueryOptions): Promise<AFSCollectionQueryResult>;
+  stat(path: string, options?: AFSStatOptions): Promise<AFSStatResult>;
+  explain(path: string, options?: AFSExplainOptions): Promise<AFSExplainResult>;
+  /**
+   * Find the `/user/index` overlay's backing provider, or undefined when
+   * unmounted (no `index:` manifest section) OR reserved-null (blocklet
+   * declares `index:` but this caller has no DID / no callerDid — see
+   * `createSessionView`'s `indexProvider` doc).
+   */
+  private findIndexOverlay;
+  private isAfsValidationError;
+  private isAfsDependencyError;
+  private searchDiagnostics;
+  private rejectIndexSearchFallback;
+  /**
+   * Parse a `read()`-returned raw content string as JSON, matching the exact
+   * fail-soft convention `IndexFollower.indexEntry` uses when hydrating
+   * changelog rows (`providers/basic/index/src/follower.ts`): non-string
+   * content is passed through untouched; a string that isn't valid JSON is
+   * kept as the raw string rather than dropped. afs-list's `performSearch`
+   * (P5 forward contract) expects a resolved `content` object for JSON
+   * entries — this is what makes that true without a second copy of the
+   * parse-or-passthrough logic living in the hydration loop below.
+   */
+  private parseEntryContent;
+  /**
+   * Hydrate index-query hits (`{ entryPath, score, matchType }` — path only,
+   * no content) into full `AFSEntry` objects by reading each `entryPath`
+   * through THIS session view (so the caller's own `/user` overlay + its
+   * per-caller isolation applies a second time, on top of the index query's
+   * own `boundDomains` isolation — belt-and-suspenders, not redundant: see
+   * design.md P5 section). A stale entry (index has it, storage doesn't —
+   * e.g. a delete that hasn't reached the follower yet) fails the `read()`
+   * and is skipped rather than surfaced as a broken result.
+   */
+  private hydrateSearchEntries;
+  /**
+   * Search-verb forward contract (P5, design.md "search verb forwarding"):
+   * a `/user/**` search first tries the caller's semantic `/user/index`
+   * (when mounted with a real provider), scoping hits to the requested
+   * subtree and hydrating them with real content via `read()`. For blocklets
+   * whose manifest declares `index:`, the index is authoritative: failures are
+   * surfaced and DID Space native search is refused because it is an O(N)
+   * content scan. Legacy/no-index blocklets keep the old direct overlay search
+   * behavior. A successful empty index result is authoritative and returns an
+   * empty array. Index results and fallback results are never unioned. Any other
+   * overlay (`/user/index` addressed directly, `/tmp`, `/space`,
+   * `/instance/settings`, replication overlays) keeps its pre-existing
+   * single-overlay-search behavior unchanged.
+   */
+  search(path: string, query: string, options?: AFSSearchOptions): Promise<AFSSearchResult>;
+  exec(path: string, args: Record<string, unknown>, options: AFSExecOptions): Promise<AFSExecResult>;
+  /**
+   * Inject `context.afs = this` so downstream provider handlers that call
+   * back into AFS (`ctx.context.afs.read`/`.write`/`.exec`/...) hit this
+   * overlaid session view — not the bare runtime root the provider was
+   * mounted into. Without this, the `/user` overlay (and any other per-
+   * caller overlay) is invisible to handler-internal AFS calls, so writes
+   * silently land on the global `/user` fs mount instead of the caller's
+   * DID-Space-projected `/user`.
+   */
+  private withSelfContext;
+  subscribe(filter: AFSEventFilter, callback: AFSEventCallback): AFSUnsubscribe;
+  /**
+   * Subscribe one overlay's backing provider, re-prefixing bridged event paths
+   * back into the overlay namespace. No-op when the overlay is unbacked
+   * (anonymous `/user`) or its provider lacks `subscribe`.
+   */
+  private subscribeOverlay;
+  beginRender(renderId: string): Promise<void>;
+  endRender(renderId: string): void;
+  getMounts(namespace?: string | null): MountInfo[];
+  initializePhysicalPath(...args: Parameters<AFSRoot["initializePhysicalPath"]>): Promise<string>;
+  cleanupPhysicalPath(...args: Parameters<AFSRoot["cleanupPhysicalPath"]>): Promise<void>;
+  setEventSink(...args: Parameters<NonNullable<AFSModule["setEventSink"]>>): void;
+  setSecretCapability(...args: Parameters<NonNullable<AFSModule["setSecretCapability"]>>): void;
+}
+/**
+ * Assemble a caller's per-session view: a SettingsResolver (instance+user
+ * settings cascade, role-aware) wrapped by a SessionUserAFS (`/user` +
+ * optional `/space` + `/tmp` + `/instance/settings`). This is the construction the daemon's
+ * `buildSessionView` chokepoint delegates to — extracted so the role→resolver
+ * wiring is unit-testable in isolation (the daemon's only remaining job is to
+ * RESOLVE `role` from the verified session before calling this).
+ *
+ * The resolver always exists (even for anonymous / no role) so
+ * `/instance/settings` carries correct capability hints + enforcement for every
+ * caller — there is no bypass path.
+ */
+declare function createSessionView(opts: {
+  base: AFSRoot;
+  userProvider: AFSModule | null;
+  tmpProvider: AFSModule | null;
+  /**
+   * Omitted → no `/space` overlay. null → `/space` reserved and NotFound
+   * (fail-closed). Provider → mounted caller DID Space root.
+   */
+  spaceProvider?: AFSModule | null; /** Caller role from the verified session; undefined → non-admin (fail-closed). */
+  role: string | undefined;
+  sessionId: string;
+  /**
+   * Derived package-schema handle for this blocklet (settings-layering
+   * Phase 1c), pre-bound to identity + base by the runtime. Optional — absent
+   * means no derived index (legacy resolution; existing call sites/tests
+   * unchanged).
+   */
+  settingsSchema?: SettingsSchemaHandle | null;
+  /**
+   * Caller's per-user semantic index provider mounted at `/user/index`.
+   * Omitted → no overlay (path falls through to `/user`); null → reserved.
+   */
+  indexProvider?: AFSModule | null;
+  /**
+   * Whether `/user` search must be served by `/user/index` because the
+   * blocklet manifest declares `index:`. Kept distinct from `indexProvider`
+   * because runtimes may reserve `/user/index` with null for no-index
+   * blocklets while direct path access still fails closed.
+   */
+  indexSearchRequired?: boolean;
+  /**
+   * Verified caller DID (from the session, never client-supplied). Forwarded
+   * to ReplicationResolver for authorship tagging and ownItem delete gate.
+   * null/undefined → anonymous (no copy-side writes).
+   */
+  callerDid?: string | null;
+  /**
+   * Replicated-collection declarations parsed from the blocklet manifest.
+   * When non-empty, a ReplicationResolver is built and mounted at the computed
+   * common ancestor prefix (e.g. "/instance"). null/omitted → no overlay.
+   */
+  replicated?: Record<string, _aigne_afs0.ReplicatedCollection> | null;
+}): SessionUserAFS;
+//#endregion
+export { SESSION_OVERLAY_PREFIXES, SessionUserAFS, assertOverlayOrder, createSessionView, isSessionPrivatePath };
+//# sourceMappingURL=session-user-afs.d.mts.map

package/dist/session/session-user-afs.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-user-afs.d.mts","names":[],"sources":["../../src/session/session-user-afs.ts"],"mappings":"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"}