Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix: a treeless clone stops sync with a clear message, and folder rules fetch nothing (GST-2331)

garrytan79b61977a980
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1f77c91bc0..e01d82589c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,7 +12,7 @@ identifiers and attribution are available in the pre-removal Git revision
## [Unreleased]
-**A managed sync no longer fetches Git objects in a partial clone (`git clone --filter`).** Every Git read a managed sync makes now runs with Git's transports and lazy fetching switched off. A file whose blob the clone never fetched is imported from your checkout when the checkout holds exactly that blob, and otherwise held alone as `git_object_missing`, with a message that names the partial clone and the `git cat-file -p <blob>` that fetches it. A blobless clone with a normal checkout syncs every file as before.
+**A managed sync no longer fetches Git objects in a partial clone (`git clone --filter`).** Every Git read a managed sync makes now runs with Git's transports and lazy fetching switched off. A file whose blob the clone never fetched is imported from your checkout when the checkout holds exactly that blob, and otherwise held alone as `git_object_missing`, with a message that names the partial clone and the `git cat-file -p <blob>` that fetches it. A blobless clone with a normal checkout syncs every file as before. A treeless clone (`--filter=tree:0`) that lacks a tree of the commit being synced stops the run with `git_object_missing`, naming the partial clone and the `git ls-tree -r -d <commit>` that fetches the trees; nothing is synced or deleted until then. The folder rules in `.gbrain/access.yml` are read the same way: a version the partial clone never fetched makes the source read as nobody, with a message that names the partial clone and the command that fetches it, instead of being fetched.
### Itemized changes
@@ -20,7 +20,10 @@ identifiers and attribution are available in the pre-removal Git revision
- `syncGit` and `syncGitAsync` (`sync-discovery.ts`), every read in `sync-blobs.ts` (`ls-tree`, `cat-file --batch`), the `git show` fallback, the delta and working-tree diff (`sync-delta.ts`), the rename-identity `cat-file` stream, the metafile head reads, the origin-evidence history walk and ignore check, the held-deletion read, the unindexed-file listing and the pending-import checks now run with both.
- `src/core/persistence/sync-entry-fault.ts`: in a partial clone the `git_object_missing` hold names the partial clone and its fix is `git cat-file -p <blob>`; in any other checkout it still names `git fsck --connectivity-only`.
- A partial clone with no checkout (`--no-checkout`) holds every committed file `git_object_missing`. When rename detection needs an older blob the partial clone lacks, the sync compares the whole tree instead: the new path imports as a new page and the old page is deleted, so that rename does not keep its page.
-- Tests: `test/sync-partial-clone-2331.test.ts` on PGLite and Postgres, with a marker on the partial clone's object fetches and a check that it never ran, plus a blobless clone that syncs a second commit after a pull.
+- `src/core/access/policy-git.ts`: the folder-rule reads every managed pass makes (`git show` and `git log` of `.gbrain/access.yml` and `.gbrain/access.approved`, and a rebuild's history replay) now run under `HARDENED_GIT_ARGS` and `NO_LAZY_FETCH_ENV` too; before, they were a managed-sync read that could still fetch in a partial clone. A policy file the commit names that the clone never fetched, or a history the replay cannot read, makes the source read as nobody, as a shallow checkout already does; the next sync that can read it clears that.
+- `src/core/persistence/sync-discovery.ts`: `syncPartialClone` and `partialCloneTreeRefusal`. The full tree walk and the reconcile level read (`sync-pass-run.ts`) stop with `git_object_missing` when a partial clone lacks a tree of the synced commit; any other listing failure is unchanged.
+- Git 2.40 to 2.44 ignore `GIT_NO_LAZY_FETCH`. There `protocol.allow=never` refuses the fetch instead, so a missing object reads as missing and nothing is fetched, the same outcome as on 2.45 and newer (checked on Git 2.40.0, 2.43.0 and 2.44.0).
+- Tests: `test/sync-partial-clone-2331.test.ts` on PGLite and Postgres, with a marker on the partial clone's object fetches and a check that it never ran: a blobless clone that syncs a second commit after a pull, both blob read paths with and without `GIT_NO_LAZY_FETCH`, two treeless clones, and folder rules whose history the clone lacks.
## [0.60.648.0] - 2026-11-10
diff --git a/docs/architecture/key-files/access.md b/docs/architecture/key-files/access.md
index dab5bb8579..32d34e5e5c 100644
--- a/docs/architecture/key-files/access.md
+++ b/docs/architecture/key-files/access.md
@@ -3,5 +3,5 @@
[Subsystem index](../KEY_FILES.md). Read only the entries relevant to your change.
Current behavior and load-bearing invariants; history belongs in Git and CHANGELOG.
-- `src/core/access/` (GBRA-218) — per-member read access inside one source. `principals.ts` normalizes frontmatter `readable_by` (bare id = `member:<id>`, `group:<g>`, ASCII case fold, space trim; anything malformed is `['!nobody']`); it is the row twin of the SQL `gbrain_access_readers()` (`test/access-principals.test.ts` holds them equal). A BEFORE trigger keeps `pages.page_readers` equal to that function (direct writes to the column are recomputed), and predicates test the array, never the function, which costs ~0.2 ms per row. A page that names readers with no derived value yet (written before the migration) reads as nobody until `gbrain repair access` (`repair/access.ts`). `members.ts` (members, groups, tombstoned ids never reused, bindings), `token-binding.ts` (the verifiers' join; a credential bound to a disabled, tombstoned or missing member is refused with `access_member_disabled`) and `caller.ts` (`remoteCallerAccess`: the identity dispatch puts on the caller-access record; stdio binds through `mcp.stdio_member`; publication re-resolves from the stored principal). In `search/private-visibility.ts` every page fragment is `accessAllowedSql` AND the privacy part: plain fragments use the empty identity (over-hide, never leak), `*ForCaller` fragments the caller's, and `GBRAIN_REMOTE_PRIVATE_PAGES`, `search.remote_private_pages` and `granted_sources` relax only the privacy part (`privacyForCaller`). A derivative of a page that names readers is hidden from every remote caller (`originAllowedSql`, which calls the SQL function `gbrain_access_origin_restricted()` only for atom, question, concept, event or `derived_from` rows, so each read plans one call instead of four subplans). Both parts lead with column tests (`page_readers IS NULL`, `type`) so row estimates follow column statistics; an expression test such as `->'readable_by' IS NULL` estimates almost no rows and sent restricted vector searches into nested-loop sequential scans. The index walk's page probe (`INDEX_WALK_PAGE_COLUMNS`) projects `page_readers`. Config `access.restrictions_present` (set by a trigger, sticky) keeps every pre-A1 path on a brain with no restriction. `check:remote-privacy-reads` keeps the two relaxations read only in `private-visibility.ts`. Tests: `test/member-read-access.test.ts` (remote matrix, both engines), `test/access-*.test.ts`. Folder rules (A2) keep whole folders of a source to named members. `folder-rules.ts` is the grammar (`.gbrain/access.yml`: `rules:` of `id`, `prefix`, `readable_by`), `classifyRulebook` (each change is narrowing or widening; the target installs only the narrowing part) and `matchingRuleIds`. `policy.ts` owns the one applied rulebook for both stores: `access_rules` (source-qualified ids), the append-only `access_policy_revisions` log, `access_pending_coverage` (prefixes that read as nobody while a narrowing restamps, or while a committed file is invalid) and `sources.config.access_store`, persisted at the first rule and changed only by `policy-migrate.ts` (journaled in `access_policy_migrations`). `proposeRevision` installs narrowing at once under a per-source row lock and holds widening for `applyApproved` (`plan_hash`, `preview_changed`); `restampSource` rewrites `pages.folder_rule_ids` in id windows, then clears pending coverage under the lock; re-proposing the same rulebook finishes an interrupted restamp. A trigger stamps `folder_rule_ids` from the SQL function `gbrain_access_folder_rules()` on insert and on slug or source change, never from git on the serve path. `policy-git.ts` is the git store (files committed through the commit door, applied by `syncAccessPolicyAt` from sync preflight and before and after every managed pass (`performManagedSync`: sync, drain, `sources refresh`, git conversion), read with `git show` at the synced commit; a database with no revision yet replays each committed `access.yml` since the `access.approved` baseline, so a rebuild holds a removal a plain commit made); `policy-transfer.ts` carries the applied rulebook through `gbrain export` and installs it before any page in `gbrain import`; `policy-notice.ts` is the `access_policy_pending` degraded notice. In `private-visibility.ts`, `folderRulesAllowedSql` sits inside `accessAllowedSql` (`folder_rule_ids IS NULL OR folder_rule_ids <@ <satisfied ids>` plus coverage conjuncts), so no hatch, grant or `--as` relaxes it, and the unrestricted short form tests `folder_rule_ids IS NULL` next to `page_readers IS NULL` (v283 triggers set `access.restrictions_present` on the first rule or pending prefix); `caller.ts`'s `folderAccessFor` fails closed to whole-source coverage. CLI: `src/commands/access-rules.ts`; doctor: `src/commands/doctor/checks/folder-access.ts`. Tests: `test/access-folder-rules.test.ts` (database store, both engines), `test/access-folder-rules-git.test.ts`, `test/access-folder-transfer.test.ts`, `test/access-folder-doctor.test.ts`. Shared agents (B, GBRA-231): `audience.ts` parses the audience a harness asserts (`X-Gbrain-On-Behalf-Of` or request-level `_meta.on_behalf_of`, 1-50 principals, `guest` = the empty identity; the same key inside tool arguments is refused) and appends each assertion to `access-audience-YYYY-Www.jsonl`. Dispatch resolves it on every remote call through `caller.ts` (`resolveAudienceIdentities`: every entry must be in the credential's live `may_act_for`, then name an enabled member or existing group); the caller-access record then carries `audienceIdentities`, and `accessAllowedForAllSql` needs one readers conjunct per identity, folder rules the intersection of each entry's satisfied set (`folderAccessForAll`). Privacy relaxes only for a one-member audience. Writes carry the audience as `WriteAuthority.actingFor` (re-resolved at publication) and agent jobs as `grant.actingFor`. Every remote response carries `_meta.access` (`appliedAccessSummary`), which `whoami` returns as `access.applied`; doctor `access_may_act_for_wildcard` (`checks/shared-agent-access.ts`) warns on `*`. Tests: `test/access-on-behalf-of.test.ts` (both engines), `test/e2e/serve-http-on-behalf-of.test.ts`. Attested actor (C1, GST-359): `actor-model.ts` (dependency-free: `x-qm-actor`, `acting_user`, `EXTERNAL_ID_RE` = 1-256 visible ASCII, `attestRightFrom`: the right counts only for a member-less credential whose token is legacy or `client_credentials`, read from `oauth_tokens.grant_type`) and `actor.ts`. `resolveAttestedActor` runs in dispatch before any work: an invalid id refuses `actor_not_attested` (`invalid_actor_id`) before any lookup, then the right, the op list (`attest_ops`, default `get_write_request,memory_recall,memory_write`), `acting_user` = header (stripped), and `actorCoverage` (the one coverage test: live right plus a live link in `access_member_links` to an enabled member, compared exactly) or `actor_unlinked`. `ACTOR_DEFERRED_OPS` (`capture`, `extract_facts`, take writes, `list_write_conflicts`) are never attestable until each is keyed to the member: refused by `parseAttestOps`, `bindCredential`, every call and the stored re-check, which also re-checks `attest_ops` for a queued write's operation and each job tool call. Under the header serve-http lists only attested tools and refuses `resources/read`. `attestedCallerAccess` is a one-member audience with privacy never relaxed (no granted sources, no hatch), never B's `may_act_for` path. Writes store `WriteAuthority.actingFor = {system, external_id, member}` and jobs `grant.actor`; `storedActorIdentity` re-resolves both through `actorCoverage` and refuses when the member changed. `linkMember` / `unlinkMember` / `listMemberLinks` back `gbrain access member link|unlink|links`; `--attest-actor` / `--attest-ops` on `auth rescope` (`members.ts`) only for a member-less legacy token or confidential client-credentials client. Migration v286. Tests: `test/access-qm-actor.test.ts` (both engines), `test/e2e/serve-http-qm-actor.test.ts`. Member facts (C2, GST-359): `member-facts.ts`. A remote `remember` from an attested actor or a lone-member credential (`callerMember`, never an audience of several) writes to `memory/members/<member>` (`memberFactPage`; `persistence/memory-prepare.ts` creates the page with `readable_by: [member:<id>]`), `visibility: private`, `infer_entity` off, the entity kept as `entity_slug`, unless the call passes `share: true` (GST-2243), which takes the ordinary world route to the subject's page; a member's explicit `visibility: "world"` is refused in `remember`'s validation (`member_share_required`), so a batch with one such item saves nothing. A member id whose page slug `slugifyPath` would change (`a--b`, `zed-`) is refused (`invalid_params`). The page must name that member alone (`memberPageIsOwn`, checked at submission and again in preparation, `memberPageNotOwned`), and remote writes under `memory/members/` go only to the caller's own page (`assertMemberPageWriter`, called from `ops/context.ts` `enforceClientSlugFence`, so every remote page write passes it; trusted local callers are unaffected). Reads widen a world-only fact list only by `memberFactAdmitSql` (a private fact on the caller's own live member page whose readers and folder rules admit the caller; `factVisibilitySql` in `engine-sql/facts.ts` and `search/fact-relevance.ts`), and `privateProvenanceFilterUnderPolicy` judges a member-page fact's source page as the caller (every other fact keeps the empty identity, so a fact from a page that names readers stays hidden from every remote caller). Writers never cross pages: `facts/single-prepare.ts` (`SingleFactIntent.page_slug`) and `trust/supersede-handlers.ts` dedup, supersede and contest only within the member page, and no other write matches a fact there (`onMemberPageSql`); consolidation skips facts whose page names readers (`readersSourcedFactSql`). Per-person keys: `callerIdentityKey` joins the hot-memory cache key (`facts/meta-hook.ts`, `::xid=`), `callerSessionKey` the `delta` cursor (`ops/facts.ts`), `sameAttestedActor` gates receipts (`persistence/authority.ts` `ownRequestAccessible`) and replays (`persistence/journal.ts`) on the stored actor, else the stored audience, and `get_agent_job` and the owner-fenced `get_job`, `wait_job`, `get_job_progress`, `list_jobs` and `cancel_job` match the job's `grant.actor` (system, external id, member) and `grant.actingFor` (the same distinct audience entries; `jobActorSql` in `minions/types.ts`), so a job or receipt with an actor or audience reads as missing to the bare client and to other actors and audiences, and one with neither to every actor and audience. Tests: `test/access-member-facts.test.ts` (both engines), `test/access-member-sweep.test.ts` (every attestable op as Bob, the bare client and an unbound credential; `test/helpers/member-sweep.ts`), `test/e2e/serve-http-member-sweep.test.ts` (two members over a real `serve --http` on a keyless repo-less brain).
+- `src/core/access/` (GBRA-218) — per-member read access inside one source. `principals.ts` normalizes frontmatter `readable_by` (bare id = `member:<id>`, `group:<g>`, ASCII case fold, space trim; anything malformed is `['!nobody']`); it is the row twin of the SQL `gbrain_access_readers()` (`test/access-principals.test.ts` holds them equal). A BEFORE trigger keeps `pages.page_readers` equal to that function (direct writes to the column are recomputed), and predicates test the array, never the function, which costs ~0.2 ms per row. A page that names readers with no derived value yet (written before the migration) reads as nobody until `gbrain repair access` (`repair/access.ts`). `members.ts` (members, groups, tombstoned ids never reused, bindings), `token-binding.ts` (the verifiers' join; a credential bound to a disabled, tombstoned or missing member is refused with `access_member_disabled`) and `caller.ts` (`remoteCallerAccess`: the identity dispatch puts on the caller-access record; stdio binds through `mcp.stdio_member`; publication re-resolves from the stored principal). In `search/private-visibility.ts` every page fragment is `accessAllowedSql` AND the privacy part: plain fragments use the empty identity (over-hide, never leak), `*ForCaller` fragments the caller's, and `GBRAIN_REMOTE_PRIVATE_PAGES`, `search.remote_private_pages` and `granted_sources` relax only the privacy part (`privacyForCaller`). A derivative of a page that names readers is hidden from every remote caller (`originAllowedSql`, which calls the SQL function `gbrain_access_origin_restricted()` only for atom, question, concept, event or `derived_from` rows, so each read plans one call instead of four subplans). Both parts lead with column tests (`page_readers IS NULL`, `type`) so row estimates follow column statistics; an expression test such as `->'readable_by' IS NULL` estimates almost no rows and sent restricted vector searches into nested-loop sequential scans. The index walk's page probe (`INDEX_WALK_PAGE_COLUMNS`) projects `page_readers`. Config `access.restrictions_present` (set by a trigger, sticky) keeps every pre-A1 path on a brain with no restriction. `check:remote-privacy-reads` keeps the two relaxations read only in `private-visibility.ts`. Tests: `test/member-read-access.test.ts` (remote matrix, both engines), `test/access-*.test.ts`. Folder rules (A2) keep whole folders of a source to named members. `folder-rules.ts` is the grammar (`.gbrain/access.yml`: `rules:` of `id`, `prefix`, `readable_by`), `classifyRulebook` (each change is narrowing or widening; the target installs only the narrowing part) and `matchingRuleIds`. `policy.ts` owns the one applied rulebook for both stores: `access_rules` (source-qualified ids), the append-only `access_policy_revisions` log, `access_pending_coverage` (prefixes that read as nobody while a narrowing restamps, or while a committed file is invalid) and `sources.config.access_store`, persisted at the first rule and changed only by `policy-migrate.ts` (journaled in `access_policy_migrations`). `proposeRevision` installs narrowing at once under a per-source row lock and holds widening for `applyApproved` (`plan_hash`, `preview_changed`); `restampSource` rewrites `pages.folder_rule_ids` in id windows, then clears pending coverage under the lock; re-proposing the same rulebook finishes an interrupted restamp. A trigger stamps `folder_rule_ids` from the SQL function `gbrain_access_folder_rules()` on insert and on slug or source change, never from git on the serve path. `policy-git.ts` is the git store (files committed through the commit door, applied by `syncAccessPolicyAt` from sync preflight and before and after every managed pass (`performManagedSync`: sync, drain, `sources refresh`, git conversion), read with `git show` at the synced commit (GST-2331: every read under `HARDENED_GIT_ARGS` and `NO_LAZY_FETCH_ENV`, so a partial clone fetches nothing; a policy file the commit names that the clone lacks, or a history the replay cannot read, makes the source read as nobody until a sync can read it); a database with no revision yet replays each committed `access.yml` since the `access.approved` baseline, so a rebuild holds a removal a plain commit made); `policy-transfer.ts` carries the applied rulebook through `gbrain export` and installs it before any page in `gbrain import`; `policy-notice.ts` is the `access_policy_pending` degraded notice. In `private-visibility.ts`, `folderRulesAllowedSql` sits inside `accessAllowedSql` (`folder_rule_ids IS NULL OR folder_rule_ids <@ <satisfied ids>` plus coverage conjuncts), so no hatch, grant or `--as` relaxes it, and the unrestricted short form tests `folder_rule_ids IS NULL` next to `page_readers IS NULL` (v283 triggers set `access.restrictions_present` on the first rule or pending prefix); `caller.ts`'s `folderAccessFor` fails closed to whole-source coverage. CLI: `src/commands/access-rules.ts`; doctor: `src/commands/doctor/checks/folder-access.ts`. Tests: `test/access-folder-rules.test.ts` (database store, both engines), `test/access-folder-rules-git.test.ts`, `test/access-folder-transfer.test.ts`, `test/access-folder-doctor.test.ts`. Shared agents (B, GBRA-231): `audience.ts` parses the audience a harness asserts (`X-Gbrain-On-Behalf-Of` or request-level `_meta.on_behalf_of`, 1-50 principals, `guest` = the empty identity; the same key inside tool arguments is refused) and appends each assertion to `access-audience-YYYY-Www.jsonl`. Dispatch resolves it on every remote call through `caller.ts` (`resolveAudienceIdentities`: every entry must be in the credential's live `may_act_for`, then name an enabled member or existing group); the caller-access record then carries `audienceIdentities`, and `accessAllowedForAllSql` needs one readers conjunct per identity, folder rules the intersection of each entry's satisfied set (`folderAccessForAll`). Privacy relaxes only for a one-member audience. Writes carry the audience as `WriteAuthority.actingFor` (re-resolved at publication) and agent jobs as `grant.actingFor`. Every remote response carries `_meta.access` (`appliedAccessSummary`), which `whoami` returns as `access.applied`; doctor `access_may_act_for_wildcard` (`checks/shared-agent-access.ts`) warns on `*`. Tests: `test/access-on-behalf-of.test.ts` (both engines), `test/e2e/serve-http-on-behalf-of.test.ts`. Attested actor (C1, GST-359): `actor-model.ts` (dependency-free: `x-qm-actor`, `acting_user`, `EXTERNAL_ID_RE` = 1-256 visible ASCII, `attestRightFrom`: the right counts only for a member-less credential whose token is legacy or `client_credentials`, read from `oauth_tokens.grant_type`) and `actor.ts`. `resolveAttestedActor` runs in dispatch before any work: an invalid id refuses `actor_not_attested` (`invalid_actor_id`) before any lookup, then the right, the op list (`attest_ops`, default `get_write_request,memory_recall,memory_write`), `acting_user` = header (stripped), and `actorCoverage` (the one coverage test: live right plus a live link in `access_member_links` to an enabled member, compared exactly) or `actor_unlinked`. `ACTOR_DEFERRED_OPS` (`capture`, `extract_facts`, take writes, `list_write_conflicts`) are never attestable until each is keyed to the member: refused by `parseAttestOps`, `bindCredential`, every call and the stored re-check, which also re-checks `attest_ops` for a queued write's operation and each job tool call. Under the header serve-http lists only attested tools and refuses `resources/read`. `attestedCallerAccess` is a one-member audience with privacy never relaxed (no granted sources, no hatch), never B's `may_act_for` path. Writes store `WriteAuthority.actingFor = {system, external_id, member}` and jobs `grant.actor`; `storedActorIdentity` re-resolves both through `actorCoverage` and refuses when the member changed. `linkMember` / `unlinkMember` / `listMemberLinks` back `gbrain access member link|unlink|links`; `--attest-actor` / `--attest-ops` on `auth rescope` (`members.ts`) only for a member-less legacy token or confidential client-credentials client. Migration v286. Tests: `test/access-qm-actor.test.ts` (both engines), `test/e2e/serve-http-qm-actor.test.ts`. Member facts (C2, GST-359): `member-facts.ts`. A remote `remember` from an attested actor or a lone-member credential (`callerMember`, never an audience of several) writes to `memory/members/<member>` (`memberFactPage`; `persistence/memory-prepare.ts` creates the page with `readable_by: [member:<id>]`), `visibility: private`, `infer_entity` off, the entity kept as `entity_slug`, unless the call passes `share: true` (GST-2243), which takes the ordinary world route to the subject's page; a member's explicit `visibility: "world"` is refused in `remember`'s validation (`member_share_required`), so a batch with one such item saves nothing. A member id whose page slug `slugifyPath` would change (`a--b`, `zed-`) is refused (`invalid_params`). The page must name that member alone (`memberPageIsOwn`, checked at submission and again in preparation, `memberPageNotOwned`), and remote writes under `memory/members/` go only to the caller's own page (`assertMemberPageWriter`, called from `ops/context.ts` `enforceClientSlugFence`, so every remote page write passes it; trusted local callers are unaffected). Reads widen a world-only fact list only by `memberFactAdmitSql` (a private fact on the caller's own live member page whose readers and folder rules admit the caller; `factVisibilitySql` in `engine-sql/facts.ts` and `search/fact-relevance.ts`), and `privateProvenanceFilterUnderPolicy` judges a member-page fact's source page as the caller (every other fact keeps the empty identity, so a fact from a page that names readers stays hidden from every remote caller). Writers never cross pages: `facts/single-prepare.ts` (`SingleFactIntent.page_slug`) and `trust/supersede-handlers.ts` dedup, supersede and contest only within the member page, and no other write matches a fact there (`onMemberPageSql`); consolidation skips facts whose page names readers (`readersSourcedFactSql`). Per-person keys: `callerIdentityKey` joins the hot-memory cache key (`facts/meta-hook.ts`, `::xid=`), `callerSessionKey` the `delta` cursor (`ops/facts.ts`), `sameAttestedActor` gates receipts (`persistence/authority.ts` `ownRequestAccessible`) and replays (`persistence/journal.ts`) on the stored actor, else the stored audience, and `get_agent_job` and the owner-fenced `get_job`, `wait_job`, `get_job_progress`, `list_jobs` and `cancel_job` match the job's `grant.actor` (system, external id, member) and `grant.actingFor` (the same distinct audience entries; `jobActorSql` in `minions/types.ts`), so a job or receipt with an actor or audience reads as missing to the bare client and to other actors and audiences, and one with neither to every actor and audience. Tests: `test/access-member-facts.test.ts` (both engines), `test/access-member-sweep.test.ts` (every attestable op as Bob, the bare client and an unbound credential; `test/helpers/member-sweep.ts`), `test/e2e/serve-http-member-sweep.test.ts` (two members over a real `serve --http` on a keyless repo-less brain).
- `src/core/ops/qm-memory.ts` (GST-359 D) — QM's memory provider pair. `memory_recall` reads the attested person's own last-24-hour facts on their member page (`listFactsSince` with `sourceMarkdownSlug`), then `rankFactsByQuestion` over the facts they may read, renders one plain line per fact (`plainFactText` strips fence and heading markers) and cuts at a line within `max_chars` (`boundFactLines`). A call that names `source_id` or `source_ids` (full surface only) reads as that scope instead: `recallSources` resolves them through `requestSourceScope` (a source outside the credential's grant is `permission_denied`), `SCOPE_READ_ACCESS` empties identity, actor and audience, so no own facts and no member-page fact are read, restricted pages stay hidden and privacy is never relaxed; the query is ranked on its first 2,000 characters (`MEMORY_RECALL_QUERY_CHARS`). `memory_write` validates 1-20 facts, derives each request id from uuidv5(member, idempotency_key) (`memoryWriteRequestId`) and saves through `remember`'s handler with `ctx.attestedOp = 'memory_write'`, which the stored write authority keeps (`WriteAuthority.attestedOp`) so publication and receipt reads re-check that operation's attest right. `qmMemoryToolResult` (dispatch) moves the result into `structuredContent` and leaves the model text in `content`; `unlinkedRecallResult` is the empty success dispatch's `actorRefusal` returns for an unlinked person. Contract fixture: `scripts/build-qm-memory-contract.ts` writes `docs/contracts/qm-memory-provider/v1.json` (frozen, byte-identical) and `v2.json` (the scope read and write; `regen:all` artifacts). Scope writes (GST-1113): `memory_write {source_id}` saves on `memory/scope` in a scope source listed in the credential's `attest_sources` (migration v293, on `access_tokens` and `oauth_clients`); `access/attest-sources.ts` holds `perCallWriteSource` (the one exemption from the one-write-source checks in `page-mutations.ts`, `memory-mutations.ts` and `persistence/authority.ts`, keyed to that slug and re-checked at publication through `actorCoverage(..., source)`), the sticky mark `sources.config.qm_scope` (set by `applyAttestSources` under row locks; `isSourceFederated` ignores federation on it), `assertScopeSourceGrant` (in `insertClientGrant`, `persistGrant`, `writeTokenGrant` and `insertUnifiedToken`) and `withoutScopeSources` (a person recall never reads a scope source). `member-facts.ts` `assertScopePageWriter` keeps other remote writers off `memory/scope`. Tests: `test/qm-scope-writes.test.ts` (both engines), `test/qm-memory-tools.test.ts` (both engines), `test/qm-memory-contract.test.ts` (drift), `test/e2e/serve-http-qm-memory.test.ts` (keyless `serve --http`).
diff --git a/docs/architecture/key-files/files-and-sync-2.md b/docs/architecture/key-files/files-and-sync-2.md
index 407f1d5af8..59416a76d0 100644
--- a/docs/architecture/key-files/files-and-sync-2.md
+++ b/docs/architecture/key-files/files-and-sync-2.md
@@ -26,7 +26,7 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL
- `src/core/persistence/sync-prescreen.ts` — #6712 PR 1 (L1): the discovery prescreen and drift baseline. After `discoverManagedSync` freezes identities, `prescreenSyncEntries` reads the pinned blobs (`readTreeBlobs`, one recursive listing for a large set) and the import provenance of every Git import of an existing page, and `classifyBaseline` marks each `prescreened` (disk blob, revision and `syncImportParserFor` fingerprint all match; bypassed under `--full` and for held paths) or `drift` (`database`: the page moved, the file did not; `both`/`unknown` in a tree walk or for a `file_drift` hold). A page whose current revision a committed managed-sync request wrote, or whose writer's publication wrote to its file (a write-through `git` effect), is not guarded (`fileBackedRevisions`), and drifted pages under `storage.keep_db` prefixes leave the manifest as drift candidates (`releaseKeepDbDrift`, `recordDriftSkip`). The run passes prescreened entries through `waivePrescreenedRun` (`sync-waivers.ts`); `freezeEntry` holds a drifted import `file_drift` (`fileDriftHold`, `sync-page-fault.ts`) unless `sameContentAtOrigin` proves it a no-op. `movedDriftHolds` re-screens drift holds whose page moved. Tests: `test/sync-prescreen-drift-6712.test.ts` (both engines).
- `src/core/persistence/sync-image.ts` — #6529: managed sync's image branch. With multimodal embedding on, `freezeEntry` (`sync-run.ts`) freezes an image entry as its bytes in base64 (`frozenImageIntent`; `rawHash` stays the file sha256, so the working-tree check and the hash no-op are unchanged) and `prepareManagedSyncMutation` (`sync-prepare.ts`) hands it to `prepareManagedSyncImage`, which runs `importImageFile` with `prepare` (the coordinated path `gbrain import` uses in `import-prepare.ts`): the importer decides the hash no-op, OCRs and embeds the image at preparation inside the sync budget (`--no-embed` skips both; the caption chunk's text vector is deferred to `embed --stale`), and the apply records `source_path`, releases the path's hold and re-reads the snapshot. A company plan refuses (`profile_incompatible`), a screening preparation (`sameContentAtOrigin`, the no-op waiver in `sync-waivers.ts` and `unchangedManagedImport` in `import-mutations.ts` return early for images) is refused rather than paid for, newer working-tree bytes or a vanished file refuse `source_changed`, and a Git rename publishes the new slug and soft-deletes the old page. `import-file.ts` records `source_path` on the legacy importer's hash-skip path too (`refreshSourcePath`), so no image import leaves it NULL. Tests: `test/managed-sync-images-5493.test.ts` (both engines), `test/embed-stale-images-managed-6529.test.ts`.
- `src/core/persistence/sync-streamed.ts` — Wave B PR 2: managed sync of a Markdown file over the 24 MiB single-string ceiling. With `pages.segmented_storage` on, `freezeEntry` (`sync-run.ts`) freezes such a file by reference instead of holding it by its size: `streamedSyncBodyRef` hashes the sha256 and the Git blob id as a stream (sha1 or sha256 by the pinned commit's length) into `intent.body_ref` (`git_blob`, or `input_file` for an uncommitted working-tree file); the journal carries no content, and a committed entry whose working tree does not hold its pinned blob, a file over `pages.max_bytes` or a non-Markdown file is held as before. `prepareManagedSyncMutation` (`sync-prepare.ts`) hands it to `prepareManagedSyncStreamed`, which streams it through `importStreamedMarkdownFile` (`page-body/streamed-import.ts`, `coordinated`; `moved` on a rename keeps an implicit type following the new path; `slug` is the admitted page, the one recording the file as its origin, as the inline import targets) and publishes database-only, recording the origin through `bindOrigin` (B-14: a renamed page keeping its origin takes the file, no twin at the path's slug); a rename moves the page first and re-seals an unchanged body (`sealSegmentedPage`). A file the streamed path refuses (a facts fence) fails its request with the refusal's code and the run holds it (`streamedRefusalHold` in `sync-screen.ts`); a dry run lists it in `screen_skipped` as `page_body_segmented`; `groupableIntent` (`sync-group.ts`) keeps it out of bulk groups. Tests: `test/large-pages/managed-sync-streamed.test.ts` (both engines), `managed-sync-streamed-crash.test.ts` (owner killed at `consumer:prepared`), `managed-sync-streamed-memory.slow.test.ts` (VmHWM), `streamed-sync-origin-b14.test.ts` (both engines).
-- `src/core/persistence/sync-entry-fault.ts` — GBRA-133 (#6712 PR 4b): the per-entry faults of a managed sync freeze, so one odd file never stops its source. `nullBytesRefusal` holds a Markdown text with U+0000 `content_null_bytes` (line of the first NUL; a UTF-16 byte order mark says save as UTF-8), from `screenFrozenImport` with holds on and as a typed run stop under `sync.holds=fail`. `filterOwnedRefusal` (GST-2312, #9024), checked first on the same two paths, holds `content_filter_owned` a blob starting with git-crypt's header or a committed blob whose path names a Git filter driver other than `lfs`, configured here or not (`pinnedFilterDriver` in `sync-screen.ts`, at the pinned commit or a company plan's revision, read with `readFilterDrivers`' batched `git check-attr --source` on git 2.40+, or `read-tree` into a temporary index and `check-attr --cached` on an older git; with `HARDENED_GIT_ARGS` and `GIT_NO_LAZY_FETCH=1`, so the attribute read runs no repository program and fetches nothing; it first checks with `ls-tree` and `cat-file --batch-check` that each `.gitattributes` that applies is present, and a path under a missing one makes `pinnedFilterDriver` throw `git_object_missing` via `missingAttributesRefusal`; GST-2331: every read of `sync-blobs.ts` runs with `HARDENED_GIT_ARGS` and `NO_LAZY_FETCH_ENV`, so the blob reads fetch nothing either and an object a partial clone lacks reads as missing). `committedContentOrMissing` (called by `pinnedContent` when the pinned read fails) imports a committed file whose blob object is gone from working-tree bytes that hash to that blob id, else throws `git_object_missing` (GST-2331: in a partial clone, a promisor remote or `extensions.partialClone` read with `syncGit config --get-regexp`, the message names the partial clone and the fix is `git cat-file -p <blob>`; otherwise `git fsck --connectivity-only`); a committed name with U+FFFD that names nothing on disk (a name that is not UTF-8) throws `path_not_utf8` first. `directoryAt` lets a deletion whose name became a directory apply (freeze and the owner's raw-hash check). `freezeFaultHold` is `freezeEntry`'s catch (`sync-run.ts` wraps `freezeEntryOnce`): `git_object_missing` and `path_not_utf8` are held under their codes; a page-body fault (`PAGE_BODY_FAULT_CODES`: `page_body_segmented`, `page_body_rows_unreadable`, e.g. a segmented page whose segment rows don't cover its body) is held `page_write_failed` with `write_failure.code` set to that code, which `sync status` classifies by the `freeze_page_body_*` rows of `SYNC_FAULT_TABLE`; any other `OperationError` and every run-scoped error (`classifyItemFailure` scope run, connection, statement timeout, lock, back-pressure, abort) rethrows, and an unexpected throw is held `page_write_failed` with `write_failure.origin: 'freeze'` and `request_id: null`, re-tested by every sync until held `HOLD_ATTEMPTS_NEEDS_HUMAN` times; a run with `ITEM_BREAKER_MIN_ITEMS` faults and no more clean freezes than faults is systemic and rethrows.
+- `src/core/persistence/sync-entry-fault.ts` — GBRA-133 (#6712 PR 4b): the per-entry faults of a managed sync freeze, so one odd file never stops its source. `nullBytesRefusal` holds a Markdown text with U+0000 `content_null_bytes` (line of the first NUL; a UTF-16 byte order mark says save as UTF-8), from `screenFrozenImport` with holds on and as a typed run stop under `sync.holds=fail`. `filterOwnedRefusal` (GST-2312, #9024), checked first on the same two paths, holds `content_filter_owned` a blob starting with git-crypt's header or a committed blob whose path names a Git filter driver other than `lfs`, configured here or not (`pinnedFilterDriver` in `sync-screen.ts`, at the pinned commit or a company plan's revision, read with `readFilterDrivers`' batched `git check-attr --source` on git 2.40+, or `read-tree` into a temporary index and `check-attr --cached` on an older git; with `HARDENED_GIT_ARGS` and `GIT_NO_LAZY_FETCH=1`, so the attribute read runs no repository program and fetches nothing; it first checks with `ls-tree` and `cat-file --batch-check` that each `.gitattributes` that applies is present, and a path under a missing one makes `pinnedFilterDriver` throw `git_object_missing` via `missingAttributesRefusal`; GST-2331: every read of `sync-blobs.ts` runs with `HARDENED_GIT_ARGS` and `NO_LAZY_FETCH_ENV`, so the blob reads fetch nothing either and an object a partial clone lacks reads as missing). `committedContentOrMissing` (called by `pinnedContent` when the pinned read fails) imports a committed file whose blob object is gone from working-tree bytes that hash to that blob id, else throws `git_object_missing` (GST-2331: in a partial clone (`syncPartialClone` in sync-discovery.ts: a promisor remote or `extensions.partialClone`), the message names the partial clone and the fix is `git cat-file -p <blob>`, and a partial clone that lacks a tree of the synced commit stops the run instead (`partialCloneTreeRefusal`, from the tree walk and from sync-pass-run.ts's reconcile level read, fix `git ls-tree -r -d <commit>`); otherwise `git fsck --connectivity-only`); a committed name with U+FFFD that names nothing on disk (a name that is not UTF-8) throws `path_not_utf8` first. `directoryAt` lets a deletion whose name became a directory apply (freeze and the owner's raw-hash check). `freezeFaultHold` is `freezeEntry`'s catch (`sync-run.ts` wraps `freezeEntryOnce`): `git_object_missing` and `path_not_utf8` are held under their codes; a page-body fault (`PAGE_BODY_FAULT_CODES`: `page_body_segmented`, `page_body_rows_unreadable`, e.g. a segmented page whose segment rows don't cover its body) is held `page_write_failed` with `write_failure.code` set to that code, which `sync status` classifies by the `freeze_page_body_*` rows of `SYNC_FAULT_TABLE`; any other `OperationError` and every run-scoped error (`classifyItemFailure` scope run, connection, statement timeout, lock, back-pressure, abort) rethrows, and an unexpected throw is held `page_write_failed` with `write_failure.origin: 'freeze'` and `request_id: null`, re-tested by every sync until held `HOLD_ATTEMPTS_NEEDS_HUMAN` times; a run with `ITEM_BREAKER_MIN_ITEMS` faults and no more clean freezes than faults is systemic and rethrows.
- `src/core/url-clone.ts` — gbrain-owned `sources add --url` clones (#6946, GBRA-130 C-2). `isOwnedClone` (config `managed_clone` or a `local_path` under the default clone dir) and `defaultCloneDir`; `urlCloneReadOnly` is the one predicate (owned clone on a brain without managed persistence) the fence writer (`fence-write.ts`, `databaseOnlyReason: 'url_clone'`), write-through (`skipped: 'url_clone'`), timeline write-through, unfenced-facts adoption, the empty-fence guard and `sourceMirrorReadOnly` consult, so nothing gbrain writes lands in a checkout it updates with `git pull --ff-only`. `urlClonePullBlock` reads the tracked changes of a clone whose pull failed and returns `pull_blocked_local_changes` with an `ask_user` fix naming the preview `gbrain repair url-clone-fences --source <id>`; `formatUrlClonePullBlock` renders it for sync's stderr (`sync/preflight.ts`) and `cycle.ts` puts it in the sync phase detail as `pull_blocked`. Test: `test/pathological/c2-url-clone-fences.test.ts`.
- `src/core/url-source-origin.ts`, `src/commands/sources-record-origin.ts` and `src/commands/doctor/checks/url-source-origin.ts` — who added a URL source (`sources.config.added_by_remote_caller`). Both add paths write it (`true` for a remote caller, `false` for the local operator); only an explicit `true` reads as remote. URL sources added before that record existed carry none, and nothing stored tells a remote caller's add from the local operator's (same row, same default clone directory); a clone outside `$GBRAIN_HOME/clones/<id>` (or a `clones/<id>` under an earlier home) proves a local add. A URL clone counts when `isOwnedClone` accepts it, so an unmarked clone at the default directory is listed too. `urlSourcesWithoutOrigin` (read-only) feeds the wave check `url_source_origin` (host-only, `resolution: 'operator'`, `warn` with an `ask_user` fix whose argv is the preview). `recordSourceOrigin(engine, ids, { origin, apply, remote })` backs `gbrain sources record-origin <id>... --remote|--local [--apply] [--json]`: it throws `trusted_local_only` unless `remote === false`, previews unless `apply`, writes `true` (`--remote`) or `false` (`--local`) in one transaction that re-reads the row `FOR UPDATE` and refuses `source_changed` if its path or URL moved; on a managed brain that transaction runs inside `withTopologyLocks` after `lockTopologyRows`, the locks a reclone takes (a held lock refuses the id `source_busy`), and `runManagedSourceClone` takes the config it clones with from its own locked admission read, so a record and a reclone never interleave. `--remote --apply` also writes `LFS_OFF_CLONE_CONFIG` into the repository's shared config (`--git-common-dir`; `git config --file`, not run in the checkout) before the row, reads the effective values back (`lockDownGaps`) and throws when a worktree-scoped or included setting overrides one, and locks down an already-remote source whose checkout lacks it (no git-lfs refusal for it unless Git cannot place the checkout, `lfs_unknown`); each key's existing values are removed before its one value is written, in a `config.lock` copy renamed over the config in one step; a throw is reported for its id as `write_failed` and the batch continues. It never removes a `true`, and refuses `--remote` for a checkout with any tracked `filter=lfs` path or a committed `.gitattributes` declaring `filter=lfs` outside a comment line (`lfs_tracked`, worded per case; read with `hardenedGitSync` `ls-files -- ':(attr:filter=lfs)'` plus every committed `.gitattributes` blob from `ls-tree -z` records split at their first tab, then `cat-file`, so clone-local attributes cannot hide one, and read again under the locks), or one it cannot inspect (`lfs_unknown`, whose reason names the cause: checkout missing, not its own repository's top level by a realpath comparison, owned by another user (`safe.directory`), or a Git read failed), because a lock-down reclone would not match the stored writer manifest there. An unborn HEAD with an empty index (a clone of an empty repository) has no committed attributes and passes. Without git-lfs files the tracked bytes are the same, so no manifest is written. Pinned by `test/url-source-origin.test.ts` (PGLite and Postgres).
diff --git a/docs/guides/error-codes.md b/docs/guides/error-codes.md
index a6df210a6d..6d2f7a7107 100644
--- a/docs/guides/error-codes.md
+++ b/docs/guides/error-codes.md
@@ -2118,7 +2118,7 @@ More: [docs/guides/write-refusals.md#git_lfs_not_enabled](../../docs/guides/writ
| Meaning | Why | Next step | Who acts · consent | Verify | Exit | Retryable |
|---|---|---|---|---|---|---|
-| A committed file's Git object is missing from the checkout and its working-tree copy differs or is gone, so managed sync holds that file alone. | An interrupted gc, a partial clone without its promisor remote or disk corruption can drop an object a commit still names. Sync imports the working-tree bytes when they hash to the committed blob id; otherwise it imports nothing from a guess, and the rest of the source keeps syncing. | In a partial clone (git clone --filter), which sync never fetches from, fetch the blob with git cat-file -p <blob> in the checkout or check the file out; otherwise run git fsck in the checkout to see what is missing and restore it with git fetch (a shallow clone) or from a backup. Then sync again; every sync re-tests the hold. | agent | `repeat the read that failed` | 1 | no |
+| A committed file's Git object is missing from the checkout and its working-tree copy differs or is gone, so managed sync holds that file alone; a partial clone that lacks a tree of the synced commit stops the run. | An interrupted gc, a partial clone without its promisor remote or disk corruption can drop an object a commit still names. Sync imports the working-tree bytes when they hash to the committed blob id; otherwise it imports nothing from a guess, and the rest of the source keeps syncing. | In a partial clone (git clone --filter), which sync never fetches from, fetch the blob with git cat-file -p <blob> in the checkout or check the file out, or, when the run stopped on a missing tree, run the git ls-tree -r -d <commit> it names; otherwise run git fsck in the checkout to see what is missing and restore it with git fetch (a shallow clone) or from a backup. Then sync again; every sync re-tests the hold. | agent | `repeat the read that failed` | 1 | no |
More: [docs/guides/write-refusals.md#git_object_missing](../../docs/guides/write-refusals.md#git_object_missing)
diff --git a/docs/guides/write-refusals.md b/docs/guides/write-refusals.md
index 69b619a30b..c26fd91cd2 100644
--- a/docs/guides/write-refusals.md
+++ b/docs/guides/write-refusals.md
@@ -109,7 +109,7 @@ of making a duplicate.
| <a id="page_write_failed"></a>`page_write_failed` (sync hold) | `page_write_failed` | A managed sync held one file because its write failed the same way three times (the same code, origin, error class and SQLSTATE in this source), with an error gbrain cannot classify: an owner exception (for example Postgres 54000 when a frontmatter tag is too long for its index), or a refusal the receipt does not explain. Until GBRA-130 every sync stopped `blocked_by_failures` at that file and the rest of the source never imported; now the file is held and the rest of the source syncs. The first two failures still stop the run, so a one-off defect never holds a file. | Read the receipt the hold names (`gbrain write-request <request_id>`, read-only). Fix the file when the error names its content (shorten the tag, split the page), or report the receipt with the gbrain version. Then `gbrain sources retry-held <source>` and the same sync. An upgrade re-tests the file on its own. A hold whose `meta.write_failure.origin` is `freeze` (GBRA-133) is different: sync could not even prepare the file (an unexpected error while reading or screening it, before any request was admitted), so it holds it on the first failure and names the error in the hold message; the next syncs re-test it on their own until it has been held 3 times, so a transient fault clears without help. When most files of one run fail that way the run stops instead (the cause is not the files). |
| <a id="content_null_bytes"></a>`content_null_bytes` (sync hold) | `content_null_bytes` | A managed sync held one Markdown file because its text holds NUL bytes (U+0000). Page text is stored as UTF-8 without NUL bytes. The usual cause is a UTF-16 file (a Windows "Unicode" save; the hold says so when the file starts with a UTF-16 byte order mark), a binary file named `.md` or a crash-padded file. Until GBRA-133 the whole managed sync stopped at that file on every run (`storage_error`, SQLSTATE 22P05) and the rest of the source never imported; now only the file waits. With `sync.holds=fail` the run stops with `content_null_bytes` instead of holding. | Save a UTF-16 file as UTF-8, remove the NUL bytes, or remove a binary file (or leave it out with `sync.exclude`), then commit and `gbrain sync --source <source> --no-pull`. The hold re-screens when the file changes. |
| <a id="content_filter_owned"></a>`content_filter_owned` (sync hold) | `content_filter_owned` | A managed sync held one committed file because Git stores it through a filter: its path has a `filter` attribute at the synced commit naming a clean/smudge driver (whether or not this checkout's Git config defines it, since the commit may have been cleaned on another machine), or its bytes start with git-crypt's header. The committed bytes are what the filter's clean program wrote (git-crypt ciphertext, for one), not the text in your checkout, and gbrain does not run a repository's filter programs during sync, so it cannot turn them into text. Sync reads the attribute at the synced commit with `git check-attr --source` (git 2.40 or newer) or, on an older git, from a temporary index of that commit with `check-attr --cached`. Those reads run with fsmonitor, hooks and every Git transport switched off and with lazy fetching off, so reading the attribute runs no repository program and fetches nothing; when a partial clone lacks a `.gitattributes` that applies to the file, the file is held `git_object_missing` instead. Every other Git read of a managed sync fetches nothing either (see `git_object_missing`). A plain-text file under a `filter` attribute nobody uses is held too: the hold is the safe side and loses nothing. Before, a filtered file imported its stored bytes as the page text, and a git-crypt file was held `content_null_bytes`. A page imported from such a file before this release is left as it is until the file changes. Git LFS pointers are not this hold. With `sync.holds=fail`, and on a company-brain source, the run stops with `content_filter_owned` instead of holding. | Leave the file out with `sync.exclude`, or commit it without the filter so Git stores its text, then `gbrain sync --source <source> --no-pull`. The hold re-screens when the file changes. For a plain-text file under a filter attribute nobody uses, remove the attribute from `.gitattributes`, commit, and run `gbrain sources retry-held <source>`: a commit that changes only `.gitattributes` does not re-screen the file. |
-| <a id="git_object_missing"></a>`git_object_missing` (sync hold) | `git_object_missing` | A managed sync held one committed file because the commit names a Git object the checkout no longer has (an interrupted `git gc`, a partial clone without its promisor remote, disk corruption) and the working-tree copy differs from it or is gone, or because a partial clone lacks a `.gitattributes` that applies to the file at that commit, so sync cannot read whether a Git filter owns it (sync fetches nothing to find out). When the working-tree bytes hash to the committed blob id, sync imports them and holds nothing. A managed sync never fetches a missing object: every Git read it makes runs with Git's transports and lazy fetching switched off, so in a partial clone (`git clone --filter`) a blob the clone never fetched fails the read and the hold names the partial clone. A blobless clone with a normal checkout syncs as usual, because checking out fetched every file it holds; a partial clone with no checkout (`--no-checkout`) holds every committed file. When rename detection needs an older blob the partial clone lacks, the sync compares the whole tree instead, so the new path imports as a new page and the old page is deleted. Until GBRA-133 the whole managed sync stopped at that file on every run. | In a partial clone, fetch the blob the hold names with `git cat-file -p <blob>` in the checkout (or check the file out), then `gbrain sync --source <source> --no-pull`. Otherwise run `git fsck --connectivity-only` in the checkout to see what is missing, restore it with `git fetch` (a shallow clone) or from a backup, then sync the same way. Every sync re-tests the hold. |
+| <a id="git_object_missing"></a>`git_object_missing` (sync hold) | `git_object_missing` | A managed sync held one committed file because the commit names a Git object the checkout no longer has (an interrupted `git gc`, a partial clone without its promisor remote, disk corruption) and the working-tree copy differs from it or is gone, or because a partial clone lacks a `.gitattributes` that applies to the file at that commit, so sync cannot read whether a Git filter owns it (sync fetches nothing to find out). When the working-tree bytes hash to the committed blob id, sync imports them and holds nothing. A managed sync never fetches a missing object: every Git read it makes runs with Git's transports and lazy fetching switched off, so in a partial clone (`git clone --filter`) a blob the clone never fetched fails the read and the hold names the partial clone. A blobless clone with a normal checkout syncs as usual, because checking out fetched every file it holds; a partial clone with no checkout (`--no-checkout`) holds every committed file. When rename detection needs an older blob the partial clone lacks, the sync compares the whole tree instead, so the new path imports as a new page and the old page is deleted. A treeless clone (`git clone --filter=tree:0`) that lacks a tree of the commit being synced cannot list that commit's files, so the run stops with `git_object_missing` instead of holding: nothing is synced and no page is deleted. Git 2.40 to 2.44 ignore Git's switch for lazy fetching, and the transports being off stops the fetch there, with the same result. Until GBRA-133 the whole managed sync stopped at that file on every run. | In a partial clone, fetch the blob the hold names with `git cat-file -p <blob>` in the checkout (or check the file out), then `gbrain sync --source <source> --no-pull`. When the run stopped on a missing tree, run the `git ls-tree -r -d <commit>` it names in the checkout, which fetches the trees, then sync the same way. Otherwise run `git fsck --connectivity-only` in the checkout to see what is missing, restore it with `git fetch` (a shallow clone) or from a backup, then sync the same way. Every sync re-tests the hold. |
| <a id="path_not_utf8"></a>`path_not_utf8` (sync hold) | `path_not_utf8` | A managed sync held one committed file because its name is not valid UTF-8 (a Latin-1 name from an older system, an archive or a network share). Git hands the name back with U+FFFD for the bytes that are not UTF-8, and no Git read or file matches that decoded name, so nothing is imported from it. Until GBRA-133 the managed sync either stopped at that file on every run or skipped it with no hold; now only the file waits and the hold names it. With `sync.holds=fail` the run stops with `path_not_utf8` instead of holding. | Rename the file to a UTF-8 name (`git -c core.quotePath=true ls-files` shows its exact bytes; `convmv -f latin1 -t utf8` converts a Latin-1 name), commit, then `gbrain sync --source <source> --no-pull`. The rename clears the hold. |
| <a id="write_interrupted"></a>`write_interrupted` | `write_interrupted` | A transient interruption kept ending this managed write: the database ended its own statements (SQLSTATE `57014`, a statement timeout or cancel) at preparation or inside its publication transaction, a statement inside that transaction ran on a plan cached before a migration changed its table (SQLSTATE `0A000`, "cached plan must not change result type"; the next claim prepares it again), or its publication ran past `persistence.publication_ceiling_ms` and its grace and the owner cancelled it. Each interruption throws the preparation away, but it is load or latency, not the write's content, so it has its own budget: the request is claimed again after a backoff (1 s, 2 s, 4 s, 8 s, then 15 s, scheduled on the request as `next_attempt_at`; no claim, root lock or connection is held while it waits, and `gbrain sources writer status` names the waiting head `transient_backoff`) up to `persistence.max_transient_retries` times (default 5, 0 to 20), and the next interruption finishes it `failed` instead of preparing it again without limit. Interruptions never spend `persistence.max_preparation_attempts`, which preparations cut off at their deadline keep ([`preparation_stalled`](#preparation_stalled)). Nothing was published: a worktree-backed write's canonical file is restored before the failure is recorded. Contention with other transactions (`55P03` lock timeout, `40001` serialization failure, `40P01` deadlock) is released as `database_contention` uncounted, and a dropped connection or a database that is restarting or out of connections is never counted. The receipt's message and owner-only `error_detail` name the interruptions (`attempts`), the retry limit (`limit`, `limit_key`), the `cause` (`statement_cancel`, `stale_plan` or `publication_ceiling`) and the SQLSTATE (`sqlstate`, public). A managed sync member is held like [`preparation_stalled`](#write_interrupted-hold): the run moves past it and the rest of the source lands, `gbrain sync status` lists the hold (class `page`, safe action `retry`, [runbook row](sync-unblock-runbook.md)), and `gbrain sources retry-held` re-admits it. A group's shared read the database cancels is charged once, to the first member that settles with it, never to every member; and the charge commits with the claim's release, so a crash between them never counts it twice. With `persistence.preparation_deadlines` off nothing is counted and no backoff applies. | Run `gbrain sources writer status --source <source> --json` (read-only: the owner, its pool, what its writes wait on), then submit the write again with a new `request_id` once the database is less loaded; for a held sync file, run `gbrain sources retry-held <source>` and the same sync with its options. A `publication_ceiling` cause on a page that legitimately takes longer to publish is the user's call: ask before raising `persistence.publication_ceiling_ms` (or the database `statement_timeout` for a `statement_cancel`). If the same write ends this way again, report its request id with `gbrain doctor --json`. Do not raise `persistence.max_transient_retries` to get past it. |
| <a id="write_outcome_unknown"></a>`write_outcome_unknown` | `write_outcome_unknown` | The database session dropped while the write was being admitted (a pooler reap, a failover, `pg_terminate_backend`), and it kept dropping through the re-reads, so whether the write was accepted is unknown (#6355). A single drop never reaches you: the admission attempt is re-run after 100, 300 and 900 ms, and every attempt begins by reading the retained `request_id`, so a re-run replays an admitted row instead of admitting again. Before this code existed the raw socket error (`write CONNECTION_CLOSED …`, `57P01`) reached the caller while the write went on to commit, and a receipt oracle took it for a refusal. | Read the request first: `gbrain write-request -- <request_id>` or `get_write_request { request_id }` (the error's `fix` names it). A committed or pending row means the write was accepted: replay the same `request_id` to wait for it. No row means it was not: submit it again with the same `request_id`. Never resubmit under a new `request_id` without that read. |
@@ -1045,7 +1045,7 @@ same on a repo-less brain and on a git-backed one.
| <a id="access_member_id_retired"></a>`access_member_id_retired` | `gbrain access member add` or `enable` named an id that `gbrain access member rm --yes` removed. Member ids are never reused, because pages and audit history may still name the removed id. Nothing was created. | Choose a new member id. `gbrain access member disable` is the reversible way to pause a member. |
| <a id="access_member_disabled"></a>`access_member_disabled` | The access token or OAuth client is bound to a member who is disabled, removed or missing, so it was refused at verification (HTTP 401, `invalid_token` with this code in the description). A credential bound to a member reads as that member, so it is refused rather than silently treated as unbound. | Ask the brain operator to run `gbrain access member enable <id>`, or to rebind the credential with `gbrain auth rescope --token <name> --member <id>` (`--member none` unbinds it; an unbound credential sees no page that names readers). |
| <a id="access_rule_invalid"></a>`access_rule_invalid` | `gbrain access rule add` was given a rule whose prefix is not a literal lower-case slug folder ending in `/` (or holds `..` or `*`), whose readers are not member ids or `group:<id>`, or whose prefix another rule already covers; nothing was written. Prefixes match slugs literally, so a pattern or typo would restrict the wrong pages. | Write the prefix as a folder such as `partners/alice-example/` and the readers as `alice-example,group:team-a`; to change who reads a folder that already has a rule, pass that rule's `--id`. |
-| <a id="access_policy_invalid"></a>`access_policy_invalid` | A source's committed `.gbrain/access.yml` (or a file given to `gbrain access rule import`) does not validate. The last applied rules stay in force and every prefix the file names reads as nobody for remote callers (the whole source when the file does not parse), so a typo never opens a folder. | `gbrain access rule list --source <id>` shows each problem with its line. Fix the file, commit it with `gbrain git commit-push`, and run `gbrain sync --source <id> --no-pull`. |
+| <a id="access_policy_invalid"></a>`access_policy_invalid` | A source's committed `.gbrain/access.yml` (or a file given to `gbrain access rule import`) does not validate. The last applied rules stay in force and every prefix the file names reads as nobody for remote callers (the whole source when the file does not parse), so a typo never opens a folder. In a partial clone (`git clone --filter`), a policy file or an earlier version of it that the clone never fetched makes the whole source read as nobody the same way, because sync fetches nothing. | `gbrain access rule list --source <id>` shows each problem with its line. Fix the file, commit it with `gbrain git commit-push`, and run `gbrain sync --source <id> --no-pull`. In a partial clone, run the `git cat-file -p` or `git log -p` the problem names in the checkout, which fetches what is missing, then sync the same way. |
| <a id="access_policy_pending"></a>`access_policy_pending` | A narrowing change to a source's folder rules is still being stamped onto its pages, so pages under the folders it touches read as nobody for remote callers until it finishes (other folders keep the last applied rules). Remote reads carry this as a notice: an empty answer there is not proof of no notes. | Wait and retry. If it stays pending the apply was interrupted: on the brain host run `gbrain access resume --source <id>` (database store) or `gbrain sync --source <id> --no-pull` (git store); `gbrain access rule status --source <id>` shows the pending folders. |
## Shared-agent refusals
diff --git a/src/core/access/policy-git.ts b/src/core/access/policy-git.ts
index 04937ec546..2883854d4d 100644
--- a/src/core/access/policy-git.ts
+++ b/src/core/access/policy-git.ts
@@ -24,7 +24,8 @@ import { serr } from '../console-prefix.ts';
import { opError, OperationError } from '../ops/contract.ts';
import { readSyncAnchor } from '../sync-anchor.ts';
import { gitChildEnv } from '../git-env.ts';
-import { gitAsync } from '../sync-git.ts';
+import { execFileBounded } from '../bounded-child-exec.ts';
+import { HARDENED_GIT_ARGS, NO_LAZY_FETCH_ENV } from '../hardened-git.ts';
import { acquireCommitLock, checkoutRoot, commitAndPush, COMMIT_LOCK_ENV, type CommitPushResult } from '../git/commit-push.ts';
import { parsePolicyYaml, rulebookDigest, serializePolicyYaml, type FolderRule, type PolicyProblem } from './folder-rules.ts';
import { clearPolicyInvalid, coverageRows, getRevision, listRevisions, markPolicyInvalid, proposeRevision, readAccessStore, writeAccessStore, type ProposalResult, type RestampProgress } from './policy.ts';
@@ -53,19 +54,45 @@ function gitShow(root: string, rev: string, path: string): string | null {
return r.status === 0 ? r.stdout : null;
}
-/** isGitWorkTree without blocking the event loop, for sync (a resident runs it in-process on a commit). */
+/**
+ * GST-2331: a Git read for sync (a resident runs it in-process on a commit) under `HARDENED_GIT_ARGS` and
+ * `GIT_NO_LAZY_FETCH`, so a partial clone fetches nothing; rejects on a nonzero exit, and `raw` keeps the output untrimmed.
+ */
+async function policyGit(root: string, args: string[], raw = false): Promise<string> {
+ const r = await execFileBounded('git', ['-c', 'core.quotepath=false', ...HARDENED_GIT_ARGS, '-C', root, ...args],
+ { env: gitChildEnv(NO_LAZY_FETCH_ENV), timeout: 30_000, maxBuffer: 100 * 1024 * 1024 });
+ if (r.error) throw r.error;
+ return raw ? r.stdout : r.stdout.trim();
+}
+
+/** isGitWorkTree without blocking the event loop, for sync. */
async function isGitWorkTreeAsync(root: string): Promise<boolean> {
- return gitAsync(root, ['rev-parse', '--is-inside-work-tree'], { silenceStderr: true }).then(out => out === 'true', () => false);
+ return policyGit(root, ['rev-parse', '--is-inside-work-tree']).then(out => out === 'true', () => false);
}
-export interface CommittedPolicy { yml: string | null; approved: string | null; commit: string | null }
+/**
+ * GST-2331: `path` as committed at `rev`: null when there is no such commit or the commit has no such file, undefined when
+ * the commit names the file and the repository cannot read it (a partial clone never fetched its object or a tree on the
+ * way, and sync fetches nothing).
+ */
+async function committedFile(root: string, rev: string, path: string): Promise<string | null | undefined> {
+ const text = await policyGit(root, ['show', `${rev}:./${path}`], true).catch(() => null);
+ if (text !== null) return text;
+ if (!await policyGit(root, ['rev-parse', '--verify', '--quiet', `${rev}^{commit}`]).then(() => true, () => false)) return null;
+ return await policyGit(root, ['ls-tree', '-z', rev, '--', path], true).catch(() => undefined) === '' ? null : undefined;
+}
-/** The policy files as committed at `rev` (never the working tree), and the last commit that touched access.yml. */
+export interface CommittedPolicy { yml: string | null; approved: string | null; commit: string | null; unreadable: string[] }
+
+/**
+ * The policy files as committed at `rev` (never the working tree), the last commit that touched access.yml, and the policy
+ * files the commit names that the repository cannot read (GST-2331: a partial clone that never fetched them).
+ */
export async function readCommittedPolicy(root: string, rev = 'HEAD'): Promise<CommittedPolicy> {
- const show = (path: string) => gitAsync(root, ['show', `${rev}:./${path}`], { silenceStderr: true, raw: true }).catch(() => null);
- const [yml, approved, log] = await Promise.all([show(POLICY_FILE), show(APPROVED_FILE),
- gitAsync(root, ['log', '-1', '--format=%h %an', rev, '--', POLICY_FILE], { silenceStderr: true }).catch(() => '')]);
- return { yml, approved, commit: log || null };
+ const [yml, approved, log] = await Promise.all([committedFile(root, rev, POLICY_FILE), committedFile(root, rev, APPROVED_FILE),
+ policyGit(root, ['log', '-1', '--format=%h %an', rev, '--', POLICY_FILE]).catch(() => '')]);
+ return { yml: yml ?? null, approved: approved ?? null, commit: log || null,
+ unreadable: [...(yml === undefined ? [POLICY_FILE] : []), ...(approved === undefined ? [APPROVED_FILE] : [])] };
}
export interface GitPolicySyncResult {
@@ -85,13 +112,20 @@ export async function syncGitPolicy(engine: BrainEngine, sourceId: string, root:
if (store === 'database') return { source_id: sourceId, state: 'skipped', reason: 'database_store' };
const files = await readCommittedPolicy(root, opts.rev ?? 'HEAD');
const rev = opts.rev ?? 'HEAD';
- if (files.yml === null && files.approved === null && store !== 'git'
- && !(await gitAsync(root, ['log', '-1', '--first-parent', '--format=%H', rev, '--', POLICY_FILE], { silenceStderr: true }))) {
+ if (files.yml === null && files.approved === null && !files.unreadable.length && store !== 'git'
+ && !(await policyGit(root, ['log', '-1', '--first-parent', '--format=%H', rev, '--', POLICY_FILE]).catch(() => 'unknown'))
+ && !(await coverageRows(engine, sourceId)).some(c => c.reason === 'invalid')) {
return { source_id: sourceId, state: 'skipped', reason: 'no_policy' };
}
const rebuild = !(await getRevision(engine, sourceId))
|| (await coverageRows(engine, sourceId)).some(c => c.reason === 'invalid' && (c.detail as { file?: string } | null)?.file === REBUILD_MARK);
if (rebuild) await markPolicyInvalid(engine, sourceId, null, { problems: [{ line: null, message: 'The folder rules are being rebuilt from git history; the source reads as nobody until the rebuild finishes.' }], commit: files.commit, file: REBUILD_MARK });
+ if (files.unreadable.length) {
+ const problems = [{ line: null, message: `${files.unreadable.join(' and ')} of source ${sourceId} at ${rev} cannot be read: the repository lacks its Git object (a partial clone, git clone --filter, never fetched it) and sync fetches nothing, so the source reads as nobody. `
+ + `Fetch it in the checkout (${files.unreadable.map(path => `git -C ${root} cat-file -p ${rev}:./${path}`).join('; ')} fetches it from the partial clone's remote) or use a clone without --filter, then sync again.` }];
+ await markPolicyInvalid(engine, sourceId, null, { problems, commit: files.commit, file: rebuild ? REBUILD_MARK : POLICY_FILE });
+ return { source_id: sourceId, state: 'invalid', problems, commit: files.commit };
+ }
let approvedFile: GitPolicySyncResult['approved_file'] = 'absent';
if (files.approved !== null) {
const approved = parsePolicyYaml(files.approved);
@@ -127,17 +161,26 @@ export async function syncGitPolicy(engine: BrainEngine, sourceId: string, root:
* A rebuild replays every committed access.yml from the approved baseline's commit on (first-parent order), so a narrowing
* that a later plain commit removed or deleted the file over is applied again and its removal held, as on the database that
* saw each commit. The whole source reads as nobody from the start of a rebuild until it finishes (an interrupted one is
- * resumed by the next sync), and a shallow checkout leaves it so.
+ * resumed by the next sync), and a shallow checkout leaves it so, as does a partial clone that lacks a tree or a version of
+ * access.yml the replay reads (GST-2331: sync fetches nothing).
*/
async function replayPolicyHistory(engine: BrainEngine, sourceId: string, root: string, rev: string, fromApproved: boolean, onProgress?: (p: RestampProgress) => void): Promise<string | null> {
- if (await gitAsync(root, ['rev-parse', '--is-shallow-repository'], { silenceStderr: true }) === 'true') {
+ if (await policyGit(root, ['rev-parse', '--is-shallow-repository']) === 'true') {
return `The checkout of source ${sourceId} is shallow, so its folder-rule history cannot be replayed; the source reads as nobody. Fetch the full history (git -C ${root} fetch --unshallow) and sync again.`;
}
- const log = (args: string[]) => gitAsync(root, ['log', '--first-parent', '--format=%H', ...args], { silenceStderr: true });
- const anchor = fromApproved ? await log(['-1', rev, '--', APPROVED_FILE]) : '';
- const commits = [...(anchor ? [anchor] : []), ...(await log(['--reverse', anchor ? `${anchor}..${rev}` : rev, '--', POLICY_FILE])).split('\n').filter(Boolean)];
+ const partial = `The folder-rule history of source ${sourceId} cannot be read: the repository lacks Git objects it needs (a partial clone, git clone --filter, never fetched them) and sync fetches nothing, so the source reads as nobody. `
+ + `Fetch them in the checkout (git -C ${root} log --first-parent -p ${rev} -- ${POLICY_FILE} reads every version, fetching what is missing from the partial clone's remote) or use a clone without --filter, then sync again.`;
+ const log = (args: string[]) => policyGit(root, ['log', '--first-parent', '--format=%H', ...args]);
+ let commits: string[];
+ try {
+ const anchor = fromApproved ? await log(['-1', rev, '--', APPROVED_FILE]) : '';
+ commits = [...(anchor ? [anchor] : []), ...(await log(['--reverse', anchor ? `${anchor}..${rev}` : rev, '--', POLICY_FILE])).split('\n').filter(Boolean)];
+ } catch {
+ return partial;
+ }
for (const commit of commits.slice(0, -1)) {
- const yml = await gitAsync(root, ['show', `${commit}:./${POLICY_FILE}`], { silenceStderr: true, raw: true }).catch(() => null);
+ const yml = await committedFile(root, commit, POLICY_FILE);
+ if (yml === undefined) return partial;
const parsed = yml === null ? { ok: true as const, rules: [] as FolderRule[] } : parsePolicyYaml(yml);
if (parsed.ok) await proposeRevision(engine, sourceId, parsed.rules, { origin: 'git', store: 'git', proposedBy: `git:${commit.slice(0, 7)}`, onProgress });
}
diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index 748f34f491..7a61442935 100644
--- a/src/core/behavior-change-notice.ts
+++ b/src/core/behavior-change-notice.ts
@@ -1503,7 +1503,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;
{ since: '0.60.637.0', id: 'purge_keeps_committed_file_gst2201', text: 'The retention purge (the autopilot purge phase, the `purge` job and `gbrain pages purge-deleted`) never removes a soft-deleted page\'s file that is committed at its source\'s last synced commit or at HEAD. A page sync deleted whose file is back is left for the sync that restores it (counted as deferred); any other such page is removed database-only (receipt `write_through.skipped: committed_file`) and its file stays. A page whose file is gone, or a person\'s delete that never removed its file (for example because another page shared it), purges as before. A page purge (`gbrain delete <slug> --purge` and the retention purge) now also redacts the timeline text the page\'s `add_timeline_entry` receipts kept (the entry\'s summary and source, `bullet`), compacted ones included.' },
{ since: '0.60.647.0', id: 'remember_share_gst2243', text: 'A member credential\'s `remember` still saves privately on `memory/members/<member>` by default, and can now pass `share: true` to save the fact on its subject\'s page for everyone who reads the source, as every non-member caller does. A member\'s explicit `visibility: "world"`, which used to be saved as private without a word, is now refused (`invalid_params`, reason `member_share_required`) and nothing is saved; `share: true` with `visibility: "private"`, or onto a page whose facts are kept private, is refused too (`share_target_restricted` for the page). Only the brain host can withdraw a shared fact. With ambient writeback on, a member credential\'s instructions say to omit `visibility` and use `share: true` for team facts, and a credential that may name a member through `x-qm-actor` is told to do so on those calls and pass `visibility: "world"` on the rest. Every `remember` reply, for any caller, now names the `page` the fact went to and its `visibility`. QM\'s `memory_write` is unchanged.' },
{ since: '0.60.648.0', id: 'sync_filter_owned_hold_9024', text: 'A managed sync now holds a committed file that Git stores through a filter (a path whose `filter` attribute at the synced commit names a driver other than Git LFS, whether or not this checkout configures that driver, or a file starting with git-crypt\'s header) as `content_filter_owned`, and the rest of the source syncs. Before, such a file imported its stored bytes (git-crypt ciphertext, for one) as the page text, or a git-crypt file was held `content_null_bytes`. gbrain still never runs a repository\'s filter programs (or `core.fsmonitor`) during sync, and reading the filter attribute fetches nothing, so a partial clone that lacks a `.gitattributes` that applies to the file holds it `git_object_missing`; the hold names git-crypt when the header matches and says to leave the file out with `sync.exclude` or commit it without the filter, and for a plain-text file under a filter attribute nobody uses, to remove the attribute and run `gbrain sources retry-held`. A page an older version already imported from such a file is left as it is until the file changes; then the file is held. With `sync.holds=fail`, and on a company-brain source (which never holds), the run stops with `content_filter_owned`. Classic (unmanaged) sync is unchanged.' },
- { since: 'TBD', id: 'sync_reads_fetch_nothing_gst2331', text: 'A managed sync now makes no object fetches in a partial clone (`git clone --filter`): every Git read it makes runs with Git\'s transports and lazy fetching switched off. A committed file whose blob the partial clone never fetched imports from the working tree when those bytes are the committed blob, and is otherwise held `git_object_missing` with a message that names the partial clone and the `git cat-file -p <blob>` that fetches it; a partial clone with no checkout holds every committed file this way. A blobless clone with a normal checkout syncs as before. When rename detection needs an older blob the partial clone lacks, the sync compares the whole tree instead: the new path imports as a new page and the old page is deleted, so that rename does not keep its page. Before, the sync fetched a missing object from the partial clone\'s remote.' },
+ { since: 'TBD', id: 'sync_reads_fetch_nothing_gst2331', text: 'A managed sync now makes no object fetches in a partial clone (`git clone --filter`): every Git read it makes runs with Git\'s transports and lazy fetching switched off. A committed file whose blob the partial clone never fetched imports from the working tree when those bytes are the committed blob, and is otherwise held `git_object_missing` with a message that names the partial clone and the `git cat-file -p <blob>` that fetches it; a partial clone with no checkout holds every committed file this way. A blobless clone with a normal checkout syncs as before. When rename detection needs an older blob the partial clone lacks, the sync compares the whole tree instead: the new path imports as a new page and the old page is deleted, so that rename does not keep its page. A treeless clone (`--filter=tree:0`) that lacks a tree of the synced commit stops the run with `git_object_missing`, naming the partial clone and the `git ls-tree -r -d <commit>` that fetches the trees, and syncs or deletes nothing until then. A version of `.gbrain/access.yml` the partial clone never fetched makes the source read as nobody, with a message naming the command that fetches it. Before, the sync fetched a missing object from the partial clone\'s remote.' },
];
/** The newest disclosed change's release: the notice id moves only when a release adds rows. */
diff --git a/src/core/error-registry.ts b/src/core/error-registry.ts
index a8ffd3e3be..0a12d1e9a9 100644
--- a/src/core/error-registry.ts
+++ b/src/core/error-registry.ts
@@ -382,7 +382,7 @@ export const CODES = {
git_target_ignored: { class: 'caller', summary: "A .gitignore rule excludes the canonical file, so its Git effect cannot commit it; the effect parks at once.", suggestion: 'Remove or narrow the rule and commit that change, then run gbrain sources writer retry-effects <source> --parked-code git_target_ignored; or keep the file out of Git and leave the effect parked.' },
git_target_unsafe: { class: 'caller', summary: "Git cannot identify the existing canonical file by its native spelling." },
git_unavailable: { class: 'retryable', summary: "A git command did not complete." },
- git_object_missing: { class: 'caller', summary: "A committed file's Git object is missing from the checkout and its working-tree copy differs or is gone, so managed sync holds that file alone.", why: "An interrupted gc, a partial clone without its promisor remote or disk corruption can drop an object a commit still names. Sync imports the working-tree bytes when they hash to the committed blob id; otherwise it imports nothing from a guess, and the rest of the source keeps syncing.", docs: 'docs/guides/write-refusals.md#git_object_missing', suggestion: 'In a partial clone (git clone --filter), which sync never fetches from, fetch the blob with git cat-file -p <blob> in the checkout or check the file out; otherwise run git fsck in the checkout to see what is missing and restore it with git fetch (a shallow clone) or from a backup. Then sync again; every sync re-tests the hold.' },
+ git_object_missing: { class: 'caller', summary: "A committed file's Git object is missing from the checkout and its working-tree copy differs or is gone, so managed sync holds that file alone; a partial clone that lacks a tree of the synced commit stops the run.", why: "An interrupted gc, a partial clone without its promisor remote or disk corruption can drop an object a commit still names. Sync imports the working-tree bytes when they hash to the committed blob id; otherwise it imports nothing from a guess, and the rest of the source keeps syncing.", docs: 'docs/guides/write-refusals.md#git_object_missing', suggestion: 'In a partial clone (git clone --filter), which sync never fetches from, fetch the blob with git cat-file -p <blob> in the checkout or check the file out, or, when the run stopped on a missing tree, run the git ls-tree -r -d <commit> it names; otherwise run git fsck in the checkout to see what is missing and restore it with git fetch (a shallow clone) or from a backup. Then sync again; every sync re-tests the hold.' },
git_conversion_blocked: { class: 'consent', actor: 'user', summary: "Converting a source to git-canonical would discard database content or cannot place it, so the apply wrote nothing.", reasons: ['both_moved', 'held_drift_both', 'held_drift_unknown_differs', 'deleted_in_git', 'uncommitted_edit', 'ignored_target', 'unparseable', 'unsafe_path', 'segmented_page', 'export_mismatch', 'git_overwrites_database', 'ignore_status_unknown', 'no_record_both_moved', 'no_record_no_evidence'], why: "gbrain sources canonical --to git applies only when every database row will be in Git or in a declared database-only class afterwards. The preview counts what would be lost or cannot be placed by category (detail lists them): both_moved and held_drift_both, a page Git and the database both changed; no_record_both_moved and no_record_no_evidence, a page with no import record whose content history shows both sides moved, or shows nothing, until the owner's --decisions file decides it; deleted_in_git, a page Git deleted that the database edited since; uncommitted_edit, a working-tree edit the adoption would overwrite; ignored_target, a page whose file Git ignores without a declared class; unparseable and unsafe_path, a committed file or path sync cannot read; segmented_page, a segmented page conversion does not adopt yet; export_mismatch, a page whose export does not read back equal; git_overwrites_database, a page version a strict pass would replace that nothing accepted; ignore_status_unknown, a target whose ignore status Git cannot read (beyond a symlink, outside the checkout, a timed-out check). There is no override.", docs: 'docs/designs/GIT_CANONICAL_MEMORY.md#conversion', suggestion: 'Relay the categories and their paths (the --dry-run preview lists them) and ask the user how each should be resolved; preview again afterwards.' },
git_conversion_delta: { class: 'consent', actor: 'user', summary: "An approved conversion found pages that changed since the approval, or decisions it did not approve, so only the unchanged pages were applied and the source stays mixed.", why: "gbrain sources canonical --to git --apply --approved applies only the pages whose slug, revision, committed blob, evidence and action are the ones the owner approved. A page that changed since, a new page, a database edit the plan would now discard, and any decision the approval did not hold stay unapplied and are listed (delta) with counts; nothing outside the approved set is applied without a new decision.", docs: 'docs/guides/git-canonical.md#approval-across-time', suggestion: 'Relay the delta list and its counts to the owner; once they decide, preview again with --approval-out and apply the new approval.' },
conversion_file_in_source_root: { class: 'caller', summary: "A conversion review list, decisions file or approval was refused because its path is inside a source's checkout.", why: "Those files name pages and paths. Written or read only outside every registered source root and the Git working tree holding it (mode 0600), they can never be synced, imported or committed.", docs: 'docs/guides/git-canonical.md#review-list-and-decisions', suggestion: 'Pass a path outside every source checkout, e.g. under ~/.gbrain.' },
diff --git a/src/core/persistence/sync-discovery.ts b/src/core/persistence/sync-discovery.ts
index 64b2b665fc..804d966332 100644
--- a/src/core/persistence/sync-discovery.ts
+++ b/src/core/persistence/sync-discovery.ts
@@ -117,6 +117,23 @@ export function syncGit(root: string, args: string[]): string {
return execFileSync('git', ['-c', 'core.quotepath=false', ...HARDENED_GIT_ARGS, '-C', root, ...args],
{ env: gitChildEnv(NO_LAZY_FETCH_ENV), encoding: 'utf8', timeout: 30_000, maxBuffer: 32 * 1024 ** 2, stdio: ['ignore', 'pipe', 'pipe'] });
}
+/** GST-2331: whether the repository at `gitRoot` is a partial clone (`extensions.partialClone`, or a remote marked `promisor`), whose missing objects sync never fetches. */
+export function syncPartialClone(gitRoot: string): boolean {
+ try { return syncGit(gitRoot, ['config', '--get-regexp', '^(extensions\\.partialclone|remote\\..*\\.promisor)$']).split('\n').some(line => /^extensions\.partialclone \S|^remote\..*\.promisor (true|yes|on|1)$/i.test(line)); } catch { return false; }
+}
+/**
+ * GST-2331: the stop for a partial clone that lacks a tree of `commit` (sync fetches nothing, so it cannot list the commit's
+ * files), or null when the repository is no partial clone or holds every tree of the commit.
+ */
+export function partialCloneTreeRefusal(gitRoot: string, sourceId: string, commit: string): OperationError | null {
+ if (!syncPartialClone(gitRoot)) return null;
+ try { syncGit(gitRoot, ['ls-tree', '-r', '-d', '-z', commit]); return null; } catch { /* a tree is missing */ }
+ return opError('git_object_missing', `A Git tree of commit ${commit} that source ${sourceId} syncs is missing from the repository.`,
+ `The repository of source ${sourceId} is a partial clone (git clone --filter) that never fetched every tree of commit ${commit}, and sync fetches nothing from a remote, so it cannot list the commit's files; nothing was synced and no page was deleted. `
+ + `Fetch the trees in the checkout (git -C ${gitRoot} ls-tree -r -d ${commit} fetches them from the partial clone's remote) or use a clone without --filter, then run gbrain sync --source ${sourceId} --no-pull.`,
+ { detail: commit, fix: { argv: ['git', '-C', gitRoot, 'ls-tree', '-r', '-d', commit], consent: [], actor: 'user', requires_exclusive: false,
+ why: 'Fetches the commit\'s missing trees from the partial clone\'s remote, so the next sync can list its files.', verify: { argv: ['gbrain', 'sources', 'status', sourceId, '--json'] } } });
+}
/** `syncGit` without blocking the event loop while Git runs (a level read: a synchronous spawn held timers for 200+ ms on a loaded host). */
const execFileAsync = promisify(execFile);
export async function syncGitAsync(root: string, args: string[]): Promise<string> {
@@ -509,7 +526,9 @@ export async function discoverManagedSync(engine: BrainEngine, opts: SyncOpts, c
for (const path of delta.manifest.deleted) put(path, 'delete');
for (const rename of delta.manifest.renamed) putRename(rename);
} else {
- const listed = syncGit(gitRoot, ['ls-tree', '-r', '--name-only', '-z', target]).split('\0')
+ let tree: string;
+ try { tree = syncGit(gitRoot, ['ls-tree', '-r', '--name-only', '-z', target]); } catch (error) { throw partialCloneTreeRefusal(gitRoot, sourceId, target) ?? error; }
+ const listed = tree.split('\0')
.filter(path => path && (!scope || path.startsWith(`${scope}/`)));
const paths = listed.filter(path => !refuse(path));
assertDistinctSyncOrigins(paths);
diff --git a/src/core/persistence/sync-entry-fault.ts b/src/core/persistence/sync-entry-fault.ts
index afff3d13bb..98e586258e 100644
--- a/src/core/persistence/sync-entry-fault.ts
+++ b/src/core/persistence/sync-entry-fault.ts
@@ -34,7 +34,7 @@ import { isWriteCapacityWait } from './admission-retry.ts';
import { PAGE_BODY_FAULT_CODES } from './sync-fault-class.ts';
import { gitBlobOid } from './digest.ts';
import { readBlobBytes, type MissingAttributes, type TreeBlob } from './sync-blobs.ts';
-import { readSyncFile, syncGit, type SyncEntry } from './sync-discovery.ts';
+import { readSyncFile, syncPartialClone, type SyncEntry } from './sync-discovery.ts';
import type { GitHoldRecord } from './sync-holds.ts';
type HoldEntry = Pick<SyncEntry, 'path' | 'sourcePath' | 'working' | 'renameFrom' | 'renameHeld' | 'action'>;
@@ -101,10 +101,8 @@ export function committedContentOrMissing(cursor: { root: string; gitRoot: strin
let bytes: Buffer | null = null;
try { bytes = readSyncFile(cursor.root, entry.path); } catch { bytes = null; }
if (bytes && gitBlobOid(bytes, blob.oid.length === 64 ? 'sha256' : 'sha1') === blob.oid) return bytes.toString('utf8');
- let partial = false;
- try { partial = syncGit(cursor.gitRoot, ['config', '--get-regexp', '^(extensions\\.partialclone|remote\\..*\\.promisor)$']).split('\n').some(line => /^extensions\.partialclone \S|^remote\..*\.promisor (true|yes|on|1)$/i.test(line)); } catch { partial = false; }
const copy = bytes ? ' and the working-tree file differs from it' : ' and the working tree has no copy of it';
- if (partial) throw opError('git_object_missing', `The Git object of ${entry.path} at the synced commit is missing from the repository.`,
+ if (syncPartialClone(cursor.gitRoot)) throw opError('git_object_missing', `The Git object of ${entry.path} at the synced commit is missing from the repository.`,
`${entry.path} is committed as blob ${blob.oid}, which the repository of source ${cursor.sourceId}, a partial clone (git clone --filter), never fetched${copy}. `
+ 'Sync fetches nothing from a remote, so nothing was imported from it. '
+ `Fetch the object in the checkout (git cat-file -p ${blob.oid} fetches it from the partial clone's remote) or check the file out, then run gbrain sync --source ${cursor.sourceId} --no-pull.`,
diff --git a/src/core/persistence/sync-pass-run.ts b/src/core/persistence/sync-pass-run.ts
index 592a8bdef1..f688ceba5c 100644
--- a/src/core/persistence/sync-pass-run.ts
+++ b/src/core/persistence/sync-pass-run.ts
@@ -24,7 +24,7 @@ import { getWriteRequestById } from './journal.ts';
import type { WriteRequest } from './model.ts';
import { managedSyncWriteDiagnostic } from './sync-write-diagnostic.ts';
import { recordedStop, replaysUnchangedRefusal, resumableRowStop } from './sync-stop-class.ts';
-import { adoptLegacyPage, incomingId, syncExcludePatterns, syncGit, type LegacyIdentity, type ManagedSyncContext, type SyncDiscovery, type SyncEntry, type SyncFileRefusal, type SyncSlugCollision } from './sync-discovery.ts';
+import { adoptLegacyPage, incomingId, partialCloneTreeRefusal, syncExcludePatterns, syncGit, type LegacyIdentity, type ManagedSyncContext, type SyncDiscovery, type SyncEntry, type SyncFileRefusal, type SyncSlugCollision } from './sync-discovery.ts';
import { assertSyncDispatchActive, type SyncAuthority, type SyncProcessingOptions } from './sync-authority.ts';
import { recordPassFenceTrend, type PassStamp, type SyncCursorOptions, type SyncIntent } from './sync-prepare.ts';
import { OPEN_AT_STAMP_CAP, passFingerprint, readPassRow, SYNC_ORIGIN_DELETED_OP, transientEnding, writePassRow, type ManagedSyncPassValue, type PassEpisode,
@@ -1013,7 +1013,11 @@ export async function runSyncPass(engine: BrainEngine, input: SyncPassInput): Pr
await save('resumable', 'timeout', false, true, true).catch(() => undefined); return result('partial', 'timeout');
}
// A Git listing that did not finish cleanly classifies nothing (design v3.2 §9): the pass stops blocked, having written nothing for that round.
- if (error instanceof SyncTreeReadIncomplete) { await save('blocked', 'reconcile_read_incomplete').catch(() => undefined); return result('blocked_by_failures', 'reconcile_read_incomplete'); }
+ if (error instanceof SyncTreeReadIncomplete) {
+ await save('blocked', 'reconcile_read_incomplete').catch(() => undefined);
+ const refusal = partialCloneTreeRefusal(context.gitRoot, sourceId, head); if (refusal) throw refusal;
+ return result('blocked_by_failures', 'reconcile_read_incomplete');
+ }
const stop = resumableRowStop(error); if (stop) await save('resumable', stop, false, stop !== 'lease_lost', true).catch(() => undefined); throw error;
} finally {
unregisterPassCost(passId);
diff --git a/test/sync-partial-clone-2331.test.ts b/test/sync-partial-clone-2331.test.ts
index e763f1524e..5bb2a404c4 100644
--- a/test/sync-partial-clone-2331.test.ts
+++ b/test/sync-partial-clone-2331.test.ts
@@ -3,8 +3,10 @@ import { execFileSync } from 'node:child_process';
import { chmodSync, existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import type { BrainEngine } from '../src/core/engine.ts';
+import { __setNoLazyFetchForTests, __setPinnedWindowForTests } from '../src/core/persistence/sync-blobs.ts';
import { readGitSourceHolds } from '../src/core/persistence/sync-holds.ts';
import { performManagedSync } from '../src/core/persistence/sync-run.ts';
+import { OperationError } from '../src/core/ops/contract.ts';
import { managedBrain } from './helpers/managed-brain.ts';
import { persistencePostgresTemplate } from './helpers/persistence-postgres.ts';
import { testBackends } from './helpers/test-backends.ts';
@@ -12,6 +14,8 @@ import { testBackends } from './helpers/test-backends.ts';
// GST-2331: in a partial clone, a managed sync read of an object the repository lacks fetches nothing, so the program the
// checkout's config names for object fetches (remote.origin.uploadpack) never runs. The file is held git_object_missing
// unless its working-tree bytes are the committed blob, and a blobless clone with a normal checkout still syncs every file.
+// A treeless clone (--filter=tree:0) that lacks a tree of the synced commit stops the run, naming the partial clone, and a
+// policy file the clone never fetched makes the source read as nobody; neither fetches.
const git = (root: string, ...args: string[]) => execFileSync('git', ['-c', 'core.fsmonitor=false', '-C', root, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
const commit = (root: string, message: string) => { git(root, 'add', '-A'); git(root, '-c', 'user.name=Example', '-c', '[email protected]', 'commit', '-qm', message); };
const note = (title: string) => '---\ntype: concept\ntitle: ' + title + '\n---\n\nThe body of ' + title + '.\n' + 'A line that keeps the file long enough to pair as a rename.\n'.repeat(8);
@@ -20,6 +24,13 @@ const live = async (engine: BrainEngine) => (await engine.executeRaw<{ slug: str
const holds = async (engine: BrainEngine) => ((await readGitSourceHolds(engine, { sourceIds: ['default'] }))[0]?.holds ?? []) as Array<{ path: string; code: string; message: string; meta: { blob_oid?: string } }>;
const dropObject = (root: string, oid: string) => rmSync(join(root, '.git', 'objects', oid.slice(0, 2), oid.slice(2)));
+/** The run's refusal: what `performManagedSync` threw, or a failure when it returned. */
+async function refusal(engine: BrainEngine): Promise<OperationError> {
+ try { await performManagedSync(engine, OPTS); } catch (error) { if (error instanceof OperationError) return error; throw error; }
+ throw new Error('the sync did not stop');
+}
+const coverage = async (engine: BrainEngine) => (await engine.executeRaw<{ prefix: string; reason: string; detail: { problems?: Array<{ message: string }> } | null }>("SELECT prefix, reason, detail FROM access_pending_coverage WHERE source_id='default' ORDER BY prefix"));
+
/** A bare server holding every object of `root` and an upload-pack wrapper that leaves `marker` when Git runs it. */
function server(root: string): { url: string; uploadPack: string; marker: string } {
const bare = join(root, '..', 'origin.git'), bin = join(root, '..', 'bin'), marker = join(root, '..', 'upload-pack-ran'), uploadPack = join(bin, 'upload-pack');
@@ -38,14 +49,14 @@ function promisor(root: string): string {
return marker;
}
-/** An upstream repository of `names` under notes/, served bare, cloned into `root` without blobs (`checkout`: with a normal checkout). */
-function bloblessClone(root: string, names: string[], checkout: boolean): ReturnType<typeof server> {
+/** An upstream repository of `names` under notes/, served bare, cloned into `root` under `filter` (`checkout`: with a normal checkout). */
+function bloblessClone(root: string, names: string[], checkout: boolean, filter = 'blob:none'): ReturnType<typeof server> {
const upstream = join(root, '..', 'upstream');
mkdirSync(join(upstream, 'notes'), { recursive: true }); git(upstream, 'init', '-q', '-b', 'main');
for (const name of names) writeFileSync(join(upstream, 'notes', name + '.md'), note(name));
commit(upstream, 'upstream');
const remote = server(upstream);
- execFileSync('git', ['clone', '-q', '--filter=blob:none', ...(checkout ? [] : ['--no-checkout']), remote.url, root]);
+ execFileSync('git', ['clone', '-q', '--filter=' + filter, ...(checkout ? [] : ['--no-checkout']), remote.url, root]);
git(root, 'config', 'remote.origin.uploadpack', remote.uploadPack);
rmSync(remote.marker, { force: true });
return remote;
@@ -133,4 +144,107 @@ for (const backend of testBackends()) describe('[' + backend + '] managed sync i
expect(await live(engine)).toEqual([]);
}, root => { remote = bloblessClone(root, ['seed', 'a'], false); });
}, 240_000);
+ test('a missing blob is fetched on neither read path, nor by a Git that ignores GIT_NO_LAZY_FETCH: the cat-file --batch window and the git show fallback each hold it', async () => {
+ for (const arm of [{ window: null, lazyOff: true }, { window: 0, lazyOff: true }, { window: null, lazyOff: false }, { window: 0, lazyOff: false }]) await brain(async ({ engine, root }) => {
+ expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');
+ writeFileSync(join(root, 'notes/missing.md'), note('missing'));
+ commit(root, 'missing');
+ const marker = promisor(root);
+ const oid = git(root, 'rev-parse', 'HEAD:notes/missing.md');
+ dropObject(root, oid);
+ writeFileSync(join(root, 'notes/missing.md'), note('missing, edited in the checkout'));
+ git(root, 'update-index', '--assume-unchanged', 'notes/missing.md');
+ const restoreWindow = __setPinnedWindowForTests(arm.window), restoreLazy = __setNoLazyFetchForTests(arm.lazyOff);
+ try { await performManagedSync(engine, OPTS); } finally { restoreLazy(); restoreWindow(); }
+ expect(existsSync(marker)).toBe(false);
+ const held = await holds(engine);
+ expect(held.map(hold => [hold.path, hold.code])).toEqual([['notes/missing.md', 'git_object_missing']]);
+ expect(held[0]!.message).toContain('partial clone');
+ expect(held[0]!.message).toContain('git cat-file -p ' + oid);
+ expect(await live(engine)).toEqual(['notes/seed']);
+ });
+ }, 240_000);
+
+ test('a treeless clone without a checkout stops the run naming the partial clone, fetches nothing, and syncs once the user fetches the trees', () => {
+ let remote: ReturnType<typeof server> | undefined;
+ return brain(async ({ engine, root }) => {
+ const stopped = await refusal(engine);
+ expect(existsSync(remote!.marker)).toBe(false);
+ expect(stopped.code).toBe('git_object_missing');
+ expect(stopped.suggestion).toContain('partial clone');
+ const head = git(root, 'rev-parse', 'HEAD');
+ expect(stopped.fix?.argv).toEqual(['git', '-C', root, 'ls-tree', '-r', '-d', head]);
+ expect(await live(engine)).toEqual([]);
+ expect((await refusal(engine)).code).toBe('git_object_missing');
+ expect(existsSync(remote!.marker)).toBe(false);
+ const [command, ...args] = stopped.fix?.argv ?? [];
+ execFileSync(command!, args, { stdio: 'ignore' });
+ rmSync(remote!.marker, { force: true });
+ await performManagedSync(engine, OPTS);
+ expect(existsSync(remote!.marker)).toBe(false);
+ expect((await holds(engine)).map(hold => [hold.path, hold.code]).sort()).toEqual([['notes/a.md', 'git_object_missing'], ['notes/seed.md', 'git_object_missing']]);
+ }, root => { remote = bloblessClone(root, ['seed', 'a'], false, 'tree:0'); });
+ }, 240_000);
+
+ test('a treeless clone whose HEAD moved to a fetched commit without a checkout stops the run and deletes nothing; a pull syncs without fetching', () => {
+ let remote: ReturnType<typeof server> | undefined;
+ return brain(async ({ engine, root }) => {
+ expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');
+ expect(existsSync(remote!.marker)).toBe(false);
+ const upstream = join(root, '..', 'upstream');
+ mkdirSync(join(upstream, 'deep', 'er'), { recursive: true });
+ writeFileSync(join(upstream, 'deep/er/c.md'), note('c')); rmSync(join(upstream, 'notes/b.md'));
+ commit(upstream, 'c'); git(upstream, 'push', '-q', remote!.url, 'HEAD:main');
+ git(root, 'fetch', '-q', 'origin'); git(root, 'reset', '-q', '--soft', 'origin/main');
+ rmSync(remote!.marker, { force: true });
+ const stopped = await refusal(engine);
+ expect(existsSync(remote!.marker)).toBe(false);
+ expect(stopped.code).toBe('git_object_missing');
+ expect(stopped.suggestion).toContain('partial clone');
+ expect(stopped.fix?.argv).toEqual(['git', '-C', root, 'ls-tree', '-r', '-d', git(root, 'rev-parse', 'HEAD')]);
+ expect(await live(engine)).toEqual(['notes/a', 'notes/b', 'notes/seed']);
+ git(root, 'reset', '-q', '--hard', 'HEAD');
+ rmSync(remote!.marker, { force: true });
+ await performManagedSync(engine, OPTS);
+ expect(existsSync(remote!.marker)).toBe(false);
+ expect(await holds(engine)).toEqual([]);
+ expect(await live(engine)).toEqual(['deep/er/c', 'notes/a', 'notes/seed']);
+ writeFileSync(join(upstream, 'notes/d.md'), note('d')); commit(upstream, 'd'); git(upstream, 'push', '-q', remote!.url, 'HEAD:main');
+ git(root, 'pull', '-q', '--ff-only', 'origin', 'main');
+ rmSync(remote!.marker, { force: true });
+ await performManagedSync(engine, OPTS);
+ expect(existsSync(remote!.marker)).toBe(false);
+ expect(await live(engine)).toEqual(['deep/er/c', 'notes/a', 'notes/d', 'notes/seed']);
+ expect(await coverage(engine)).toEqual([]);
+ }, root => { remote = bloblessClone(root, ['seed', 'a', 'b'], true, 'tree:0'); });
+ }, 240_000);
+
+ test('folder rules whose history the partial clone never fetched are not fetched: the source reads as nobody, naming the partial clone, until the user fetches them', () => {
+ let remote: ReturnType<typeof server> | undefined;
+ return brain(async ({ engine, root }) => {
+ await engine.executeRaw("INSERT INTO access_members (id) VALUES ('alice-example')");
+ await performManagedSync(engine, OPTS);
+ expect(existsSync(remote!.marker)).toBe(false);
+ const blocked = await coverage(engine);
+ expect(blocked.map(row => [row.prefix, row.reason])).toEqual([['', 'invalid']]);
+ expect(blocked[0]!.detail?.problems?.[0]?.message).toContain('partial clone');
+ expect(blocked[0]!.detail?.problems?.[0]?.message).toContain('git -C ' + root + ' log --first-parent -p HEAD -- .gbrain/access.yml');
+ expect(await live(engine)).toEqual(['hr/x']);
+ await performManagedSync(engine, OPTS);
+ expect(existsSync(remote!.marker)).toBe(false);
+ git(root, 'log', '--first-parent', '-p', 'HEAD', '--', '.gbrain/access.yml');
+ await performManagedSync(engine, OPTS);
+ expect(await coverage(engine)).toEqual([]);
+ }, root => {
+ const upstream = join(root, '..', 'upstream');
+ mkdirSync(join(upstream, '.gbrain'), { recursive: true }); mkdirSync(join(upstream, 'hr'), { recursive: true }); git(upstream, 'init', '-q', '-b', 'main');
+ const rule = (id: string) => ' - id: ' + id + '\n prefix: ' + id + '/\n readable_by: [alice-example]\n';
+ writeFileSync(join(upstream, 'hr/x.md'), note('x')); writeFileSync(join(upstream, '.gbrain/access.yml'), 'version: 1\nrules:\n' + rule('hr')); commit(upstream, 'one');
+ writeFileSync(join(upstream, '.gbrain/access.yml'), 'version: 1\nrules:\n' + rule('hr') + rule('ops')); commit(upstream, 'two');
+ remote = server(upstream);
+ execFileSync('git', ['clone', '-q', '--filter=blob:none', remote.url, root]);
+ git(root, 'config', 'remote.origin.uploadpack', remote.uploadPack);
+ rmSync(remote.marker, { force: true });
+ });
+ }, 240_000);
});