Project and Memo queries
The production Project read services enforce Workspace/Restricted policy from
backend revision d0efbb75. Verify the target server's schema when using another
environment. Project access-policy and grant-management mutations remain REST;
Memo content, CRDT synchronization, and revision-protected editing are unchanged.
Restricted project access
Project discovery, namespace profile counts, name search, direct ID/slug reads and tree queries use
the project's effective access mode before pagination. workspace preserves
existing organization-member/public baselines; restricted requires namespace
ownership or an applicable explicit user/team grant. Absent legacy mode values
retain workspace. A stable project ID remains scoped to its stated namespace;
a mismatched pair returns not found rather than resolving another owner.
REST catalog responses include normalized accessMode on each project and
accessPolicy: { apiVersion: 1, modes: ["workspace", "restricted"], atomicCreate: true }
when the backend supports atomic restricted creation. Clients must check that
capability before sending confidential creation intent to an older server.
GraphQL uses the same underlying filtered read services. The GraphQL schema does
not expose accessMode, the REST atomic-create capability, an effective-audience
query, or Project policy/grant-management mutations. Do not copy REST fields into
a GraphQL selection or invent equivalent mutations. Use the authenticated REST
policy, audience and grant endpoints for those operations.
Project access management documents the policy and grants endpoints. Restricting a Project removes project-derived baseline access, not independent resource shares or namespace-level resource policies.
Separate associations from choices
| Question | GraphQL | REST |
|---|---|---|
| Which projects can this viewer access? | projectCatalog | GET /namespaces/:namespace/projects?search=design&page=1&pageSize=50 |
| Where is this Memo actually associated? | note.nodes | GET /namespaces/:namespace/resources/note/:noteId/projects?view=nodes |
| Which Bindrs can the picker offer in this project? | bindrs | GET /namespaces/:namespace/projects/:projectSlug/bindrs?view=choices&search=design&first=20 |
The GraphQL resolvers and these REST views use the same underlying visibility,
project permission, resource-readability, and association services. Their wire
shapes differ: GraphQL selects fields and wraps results in data; REST returns
its resource response directly. The view=nodes REST association view permits
authorized anonymous reads of public resources; the legacy default response
requires a signed-in caller. Unreadable resources are not exposed by the shared
service.
The existing resource-project REST response without view=nodes remains a
compatibility response that mixes candidate projects with bound and canBind.
New clients should use the views above instead. The existing Bindr response
without view=choices also keeps its prior tree-list contract.
Live project inventory (unreleased)
GET /namespaces/:namespace/projects/:projectSlug/resources?scope=all is the
Project root's live #all query. It includes readable, untagged resources at every
depth without creating a Bindr or stored membership. It cannot be combined with
parent or bindr. Existing calls without scope=all retain their folder or
Bindr listing behavior.
The response acknowledges scope: "all" and returns items, page, pageSize,
total, and totalPages. Each item has kind, a stable key, name, path,
createdAt, updatedAt, and archivedAt. A kind: "node" item carries node
with the existing Project-resource fields and Bindr chips. A kind: "native"
item carries a native target: run, run item (metric, track, file, parameters),
run folder, or project file. Main-homed tree objects occur once, through their
authorized Node rows. Ordinary tree folders remain the separate folder-navigation
query; native folders retain their existing native destination.
The existing Project kind chips use filter=memos or filter=bindrs with
scope=all. Their predicates apply to the same complete authorized inventory
before totals and page boundaries: Memo content or content with an existing live
Project Bindr membership, respectively. Navigation containers remain available,
as in the existing root filters. Native memberships use their immutable target
identities; no new membership kinds are created. Calls without a filter show all.
search matches names and paths across the complete readable union before
paging. sort accepts recent (default), oldest, name-az, name-za,
created-newest, or created-oldest; stable item keys break ties. Active resources
are the default; includeArchived=true includes archived resources without
including deleted or trashed targets. type narrows to the existing mounted
resource types and excludes native targets. Counts describe the entire filtered
answer, not just the loaded page. Pages are live reads, not a snapshot token;
concurrent edits can change subsequent pages.
Project access, independent Memo authority, and folder and Bindr discovery rules
remain enforced before counts and paging. Hidden Bindr names do not appear in
affiliation chips or qualify content for the Bindr filter. Main-homed run items
are included only when their run passes the authorized tree query. Native metadata
uses the recorded home and current lifecycle state. No metric points, track
entries, file bytes, or parameter values are returned. A required native home
failure fails the inventory; clients must not replace it with an empty native
family or treat a legacy resources response as an all response. Servers
require the additive private Dash runItemSummaries read operation before the
gateway uses this query; deploy Dash first, then the gateway, then the UI. When native experiments are disabled, that surface is absent.
Memo authority on filing reads (implementation)
Project access does not grant access to a filed Memo. REST project-resource, Bindr-member and folder-child listings omit unreadable Memos before name search, sorting, page offsets and totals. Bindr-tree member counts include only visible live members. Legacy Memo reverse project and Bindr lookups return 404 when the Memo is unreadable; project-role flags do not bypass this prerequisite. The same independent check protects GraphQL Memo metadata, children and Memo associations. Cached filing names and Memo IDs are not returned when Memo access is denied. Folders and other resource types retain their existing rules.
Each filing read resolves current project access, live Memo ownership and Memo access in one database read snapshot. Accepted shares qualify by the active recipient and Memo ID while the live share link remains enabled; cached grant namespace and stored role do not replace current policy. The live Memo share role controls independent link editing. Explicit user/team Project grants also authorize live same-namespace attachments: READ permits reading, while WRITE and ADMIN permit supported content editing. Public Project visibility alone does not open a private Memo. Arbitrary legacy foreign-namespace mounts remain unsupported even when both resources are readable; this change does not enable transfer bindings, writers or cutover.
A snapshot is local to a read operation. Separate requests and GraphQL field resolutions can observe newer state; they are not a durable access capability. Subsequent content reads and mutations must recheck current authority.
The compatibility roots projects, project and Namespace.projects share
authorization within one request. A namespace's project list is read once
however many aliases select it, and project on a project those reads
already authorized returns that project rather than authorizing it again. The
result therefore reflects authorization from earlier in the same request.
Nothing is shared across requests, and children and bindrs still
re-authorize in their own snapshot. Their arguments, results and ordering are
unchanged; new clients should still use projectCatalog.
These roots remain unbounded. projects without namespaceSlug and
namespaces { projects } return every visible project in one response, and the
GraphQL endpoint does not reject queries by depth, alias count or cost. The
request-local sharing above is a partial cost reduction
(#1370),
not a limit.
Archive state and associations
Note.archivedAt and Node.archivedAt describe independent archive state.
Node.children(includeArchived: true) includes archived items; active children
are the default. Archiving does not remove project filings or Bindr membership,
so note.nodes continues to describe actual associations. These association
reads are not an active-only content catalog. The legacy REST contents and
descendants inventory endpoints also retain archived entries when the archive
filter is omitted; pass includeArchived=false explicitly for active browsing.
See Memo and folder archival for REST filters, saved-edit restoration, permissions and current client operations.
Query a Memo's locations
Variables below use illustrative values. Replace them with a namespace and Memo ID that the caller can read:
nodes contains actual resource Nodes in visible projects, never candidate
projects. An empty list means no visible associations, not proof that no hidden
association exists. An unreadable or missing Memo returns note: null.
Node.path is the existing comma-delimited ancestor path, not the full file
path or a parent ID. For example, a Node named API design with
path: ",example-project,design-docs," sits beneath that ancestor path. Project
ownership comes from projectNodeId and the resolved project, not parsing the
path. No folder or storage migration is part of these reads.
node.bindrs means Bindrs tagging that Node, not every Bindr owned by the
project. It is resolved through membership records. Project objects retain the
GraphQL Node type and stable ID for Apollo normalization.
The equivalent REST view returns { nodes, total }; each Node includes its
project and attached Bindrs. No bound or canBind field is needed in that view.
Search project choices
The catalog is scoped to one namespace and returns authorized projects, including project-specific grants. Search is performed on the server. The default page size is 50; the maximum is 200. Fetch subsequent pages when needed instead of treating the first page as the complete set of projects.
projectCatalog also accepts counts: Boolean = true. A picker that never
shows bindrCount, datasetCount, pipelineCount or activeJobCount can pass
counts: false so the server skips their aggregation on every page; those four
fields then return null. Projects, total, canCreate, role and
permissions are the same either way. Omitting the argument keeps the counts.
A server without this argument rejects the whole query, so check the target
schema before sending it.
canCreate is permission to create a project in the namespace.
permissions.content.create is permission to add content within a particular
project. For an add-project picker, exclude projects already present in
note.nodes and offer projects with content creation permission. The mutation
still checks project authorization and resource readability. Under the
released backend Project resource access contract,
new attachments also require the resource's independent sharing-management
permission: read access alone cannot redistribute it. Authorization is
re-evaluated in the mutation transaction.
Search Bindr choices on demand
The default page size is 20; the maximum is 100. Run this only when the picker needs choices. For another page, pass the returned
endCursor as after; reset the cursor whenever the project or search changes.
Treat cursors as opaque. REST uses the same { nodes, pageInfo } response shape
and accepts the cursor as an URL-encoded after query parameter. The REST path
identifies the project by namespace and slug; GraphQL uses its Node ID.
These are live listings, not transactionally frozen snapshots. Concurrent edits may change choices between requests. Mutations remain authoritative and must revalidate permissions and membership constraints.
Execute a GraphQL request
Save any query above to query.graphql and its variables to variables.json.
Set the API base URL and an existing DreamLake token in your shell environment:
GraphQL errors can arrive with HTTP 200; inspect errors before using data.
For Apollo clients, select stable IDs and keep project objects as Node.
Refresh associations after existing REST mutations. Cancel superseded picker
requests, prevent stale identity responses from entering the cache, and isolate
explicit anonymous previews from authenticated cache entries.
Ownership preservation inventory
GET /namespaces/:namespace/ownership/resources/project/:id/manifest requires
current source namespace ownership. Project ADMIN alone does not authorize this
inventory. The response adds preservation alongside the existing structure,
filings, grant IDs and expectedVersion:
| Field | Meaning |
|---|---|
preservation.projectGrants | Existing grant id, projectId, granteeId, teamId, role, kind (direct-user, team, or invalid) and recipientState. Team eligibility is not established. |
preservation.noteShares | Accepted record id, noteId, userId, cached namespaceId, ownerMatches, storedRole, sharingEnabled, live linkRole and recipientState. Includes all live source-owned Memos filed in this project, even if not selected for transfer. |
recipientState | active, unavailable, or unresolved; legacy identities that cannot be checked remain explicit. These states do not establish effective destination access. |
linkRole is read or write while sharing is enabled, otherwise null.
It can differ from the accepted record's storedRole; namespace membership may
confer stronger access. No bearer token, private Memo body or storage key is
returned. Foreign-owned and deleted Memos do not expose their acceptance records.
The source version binds the inventory and sharing policy. Incomplete parent
inventory or an aggregate above 10,000 Memo identities, grants and accepted
records returns 422 MANIFEST_TOO_LARGE, never a truncated preservation list.
Project transfer previews also include this inventory and destinationAuthority
with action: "ownership.accept", the requested namespaceId, checked actorId
and allowed. Authority and inventory are read in the same transaction. A
source-only caller receives allowed: false without destination names or
authority-parent details. Authorized authority evidence participates in the
preview dependency hash; it is not durable acceptance or a reservation.
These fields report existing access records, not approved retention. Whole-Project execution requires the complete owned-Note manifest, an enabled Project adapter and explicit destination-owner acceptance under the selected retention policy. Reading the manifest or preview changes no grant, filing or ownership.
External Memo filing evidence
The same owner-only manifest and project preview add externalFilings for all
live source-owned Memos filed in the root project, including unselected Memos.
Each record retains filingId, projectId, noteId and
currentNoteNamespaceId. A preview adds proposedNoteNamespaceId only when that
Memo is explicitly selected. This does not select or move the external project.
currentActorProjectRead and currentActorNoteRead are independent observations
in the same transaction. Source ownership establishes the caller's current Memo
authority; every external project's current project:read policy is checked
separately. Project roles and Bindr tags never grant authority over a foreign
Memo. The future required policy is project-and-note; every record retains
disposition: "requires-reviewed-cross-owner-support". Current access is not
proof of access after the proposed owner changes, nor a new reader capability.
Only a caller with current access to the external project receives its
projectNamespaceId, filing path/name and bindrMemberships (membership ID
and Bindr ID). Those fields are null when denied; opaque filing/project/Note
IDs remain so a reference cannot silently disappear. Private parent, filing,
Bindr membership provenance and grant data enter deterministic source hashes,
not the response. Current actor/project decisions enter preview dependencies.
The complete external inventory has a separate 10,000-record aggregate limit
across Memo identities, filings, project parents, Bindr memberships, Bindrs and
project grants. Overflow returns 422 MANIFEST_TOO_LARGE. Missing, deleted or
mismatched project/Bindr parents and unresolved namespace identity return
422 EXTERNAL_FILING_RECONCILIATION_REQUIRED; no partial evidence is returned.
Existing per-Note bounds and execution gates still apply. Artifact ownership
and its adapter remain separate, unsupported work. No reference or grant is
detached, approved for retention or mutated by these reads.
Project resource inheritance
Public Project metadata access never opens a private attachment. Explicit
Project user/team grants contribute READ or supported content WRITE to current
and future attachments. Resource-own permissions and other live Project grants
remain valid; removal affects only its corresponding contribution.
A filed Host (resourceType: "host") is placement only and receives no Project
contribution; see Hosts in Projects.
In the compatibility project-choice response, canBind requires Project WRITE
or ADMIN plus independent resource sharing-management authority for a new
attachment. A readable resource or public visibility does not permit
redistribution. Grouping an existing live attachment into a Bindr in that same
Project requires Project write authority and resource readability, without
another sharing-management check. bindable=true uses the same rule.
Resource lists filter before paging and totals, and reverse Project/Bindr queries
check resource readability. A filing Node requires both underlying resource read
permission and access to its containing Project. Canonical resource references
are resolved from live catalog identities, including historical mounts without
metadata.resourceRef; editable filing titles are not resource addresses.
Completed-transfer filings and historical read aliases
The whole-Project transfer removes other-Project Memo mounts by default, ending their inherited access without deleting the moved Memos or their data. Explicit opt-in preserves approved existing foreign-namespace Memo mounts only through private completed journal evidence and current ownership history. The destination approves their existing live Project audience; implicit public READ never exposes private Memos. A later aborted transfer requires exact source-restoration proof. Arbitrary new foreign mounts or expanded cross-namespace Project grants remain unsupported.
Resource references use the Memo's canonical current namespace. Filing Project navigation retains its own namespace. Old namespace Note/NoteFile URLs may resolve only as verified read aliases and reauthorize in the current namespace; all writes remain canonical. Historical content/publication addresses are not rewritten. Whole-Project transfer is production-accepted; same-namespace sharing continues independently. See the transfer contract for the bounded live verification scope.
REST filing Node/Project responses carry their actual namespaceSlug;
GraphQL Project.namespace { slug } identifies the filing Project's namespace.
Server-derived, top-level resourceNamespaceId/resourceNamespaceSlug identify
the canonical Memo namespace independently, joined from current live Memo and
Namespace records. Editable Node metadata cannot supply those fields; unresolved
owners return null rather than a guessed namespace.
Do not derive a Project backlink from the Memo's namespace or Project name alone:
retained Projects in different namespaces may have the same name.
Project URLs can retain their original filing context with a
noteNamespace selector for the current Memo owner. A new Memo created/extracted
inside that foreign-Project Memo pane uses the Note-owner namespace and omits an
automatic foreign Project mount; Project-column creation uses the actual Project
namespace. These routes retain their independent creation checks.
Whole-Project transfer plan and blocked items
GET /namespaces/:slug/ownership/resources/project/:id/transfer-plan requires
current source-namespace owner authority. A compatible backend includes direct
ordinary files, images, videos and supported byte-backed leaves alongside the
Project and its owned Memos. The optional fileCounts object reports file,
image and video counts; other supported byte-backed leaves count as files.
Clients must still inspect the complete server plan and execution readiness.
A rejected plan can return HTTP 422 with owner-only
error.details.blockers. Each blocker includes code, action and, where
applicable, item: { id, name, path, kind }. For example, an episode Node can
produce UNSUPPORTED_PROJECT_CONTENT. Direct Project files retain their existing
storage metadata; a missing physical object does not become a transfer blocker. The dialog lists these affected
items rather than showing only a generic failure. No storage key, signed URL,
credential or private execution journal belongs in this response.
This list does not make the inventory partial or authorize transfer around a blocked item. Fix the item, obtain a fresh complete plan and review again. Existing authorization and not-found responses must not disclose this owner-only inventory. See the transfer contract for scope, storage semantics and existing signed-URL lifetimes.
Active Project transfer listing
GET /namespaces/:slug/ownership/transfers accepts direction=incoming|outgoing
(default incoming). Incoming listing requires current ownership.accept
authority; outgoing requires ownership.transferOut. The optional resourceType
accepts only canonical project, source or note, never internal execution
keys. Omitting it keeps the existing supported-resource listing.
By default, or with activeOnly=false, the response remains
{ apiVersion: 1, operations: [...] } for at most the most recent 100 requests;
it has no hasMore field and is not complete history. activeOnly accepts only
true or false. With activeOnly=true, the database query excludes expired
pending requests and selects unexpired pending, preparing, committing,
aborting and recovery-required states. The response is
{ apiVersion: 1, operations: [...], hasMore: boolean }, with at most 100
operations. hasMore signals the bounded query limit, not an exact total.
The Web Projects banner and default Transfers page request
activeOnly=true&resourceType=project. This keeps newer completed history from
hiding older active requests. A capped response is displayed as 100+, without
claiming an exact count of pending requests. An active response missing hasMore
is an incompatible response, not an empty inbox. These query options add no
endpoint, schema migration, CLI flag or SDK argument. Public Project resource
references remain project across compatible execution versions.
Recursive Project search (implementation)
The Project/folder browser can request ranked descendant search:
Use parentId instead of namespace and project to search within one folder.
The server authorizes the containing Project and checks current resource access
on every page. Results never cross the Project boundary. Direct matches come
first, followed by descendants; within each group, exact names precede name
prefixes and then substrings. Equal ranks use stable path/name order. Returned
searchParentPath, searchAncestors, and pathIds describe the actual parent
chain, so opening a nested result preserves its breadcrumb.
The response identifies searchMode: "project-recursive-v1" and returns nodes,
hasMore, and nextCursor. It does not return an exact total or page count.
Send after=<nextCursor> with the same search scope to continue. An empty page
with hasMore: true means the bounded candidate page contained no readable
results; it does not mean the search is exhausted. The browser continues normal
cursor pagination rather than fetching every folder or filtering a downloaded
Project tree. Servers without this mode produce an explicit unavailable/upgrade
message; the browser does not silently substitute direct-child-only results.
Cursors are encrypted and authenticated with a purpose-separated key derived from the existing server signing secret. Their scan positions can include unreadable candidates and must never be exposed as plain or merely signed JSON. They bind the actor, namespace, Project, folder path, query, mode, and rank position, expire after one hour, and grant no access. Changing the query/scope, expiry, or signing-key rotation requires restarting the search.
Each request returns at most 50 results and examines at most 200 matching
candidates for resource authorization. These are not bounds on index keys
examined: sparse case-insensitive substring searches can scan more keys within
the scoped Project. Candidate queries use the existing unique
Node(namespaceId, path, name) index with an explicit hint and index-order sort;
raw candidate work shares a 2-second database maxTimeMS budget. Resolving only
the returned page's ancestry has a separate 2-second database budget and a
2,500-ancestor metadata limit. Authorization and the complete HTTP request are
not covered by those two database budgets. Exhausted query, index, or ancestry
budgets return an explicit unavailable/error response rather than an unindexed
fallback or a misleading empty success. Provision/verify that existing index
and the signing-key configuration before enabling the new browser consumer.
Ordinary browsing without recursive=true keeps its existing child-only
ordering, page offsets, counts, and response format. This change adds no CLI
command, mutation, payload download, or new public skill procedure.