RFC: Material library — folders, asset-pool reference roots, and agent tools

[LING-6150]

Status: Accepted, in implementation · Area: materials, storage, agent runtime, workbench · Builds on: #1153, #1669 (Discussion #1657)

Updated 2026-10-01 with the decisions from this discussion: no undo or result cards in the first batch (§6), a revised phase plan delivered through integration/material-library, the release conditions for roots, and the UI name (§10).

Summary

This RFC gives uploaded files an owner-scoped library with folders, extraction reused across conversations, one set of operations shared by the page and the agent, and a one-line summary of each agent change in the conversation. Originals and extraction outputs are stored in the asset pool, with library entries as their reference roots. Composer uploads go into Unfiled and are attached to the conversation, and the composer's @ menu searches the whole library.

In the UI the feature is called Knowledge base (知识库); code and APIs keep material and material library (§10).

The library is a page opened from the bottom of the left rail. It is not a tab next to Chats and Courses, nor a pane beside the chat. The agent can organize materials and start extraction; store_material is not given to the agent in the first batch, and delete_material is page-only.

All statements about current behavior were checked against upstream main at 1c70e86a. Everything else is a proposal.

Problems and goals

Uploads are stored durably, but there is nowhere to manage them. POST /api/materials records an owner_material row and writes the file to MaterialByteStore. There are no folders and no rename or delete operation; the deleted_at column exists, but nothing writes it. GET /api/materials requires a session id and lists only that session's materials.

Extraction cannot be reused across conversations. bindOwnerMaterialsToSession copies the file's bytes into the session and creates a new session material id, and extraction runs on that session row. A second conversation starts from scratch.

Library assets need to stay alive without a course. Today only document_asset_refs commits a pending pool allocation and keeps it alive: a new allocation that no course names expires, and removing the last course reference starts collection grace. Library uploads need a reference root of their own.

The goals are:

• a visible home for every upload;
• extraction that is done once and reused;
• pool deduplication, quota and reclamation for materials;
• agent organization the teacher can follow, with a one-line summary of each change;
• configurable upload limits that the UI shows before an upload starts.

Relationship to #1153

#1153 defined the storage identity of materials. Its parts 0, 1, 2 and 4 were merged as #1154, #1164, #1168 and #1172. #1242 later states that the "asset registry keeps zero runtime write wiring" and that "legacy/inline conversion modules [were] deleted"; the manifest and the extraction cache were removed in the same change. #1524 brought workbench image and video generation back to the pool. Material uploads, extraction and use_material_media still use byte stores.

#1153 decision	Merged as	State on main today	This RFC
Part 0: sources enter the pool; extraction takes an asset id	#1154	Ingest wiring removed by #1242; extract-by-id compatibility and provider versions remain	Restore ingest on the owner model
Part 1: extraction cache and lineage of derived assets	#1164	Cache removed by #1242; extraction still reports id@version	Owner-scoped cache; lineage stays above storage
Part 2: manifest and atomic list/read tools	#1168	KV manifest removed by #1242; current tools are session-scoped	Owner rows, a library scope, and organizing tools
§5: the library as reference root	The earlier manifest held its own pool entries	The server lifecycle has no library root	Add explicit root references
Part 3 / §6: copy-on-use for courses	No merged implementation	Media is still copied to classroom-media paths	Allocate separate course-use entries
Part 4: legacy base64 conversion	#1172	Converters removed by #1242	Out of scope for this batch
Non-goal: no management UI	No management page	No workbench material library	Add a page and folders

What is different from last time

In #1168, the manifest was a per-principal KV list keyed by content digest. It kept files from being collected by holding its own pool entries. #1242 removed it. This proposal is different in three ways:

• Server lifecycle. #1472 and #1473 added pending expiry, reference commits and reclamation. Holding an entry is no longer enough to keep its bytes.
• Owner seam. feat(auth): owner identity seam — pluggable authenticator, owner-keyed persistence, host hooks, claims #1669 provides resolved owners, per-owner asset partitions and atomic claims, so the manifest can be owner-keyed server rows.
• Explicit roots. Library references take part in lifecycle checks alongside course references. Storage decides retention; folders, lineage and retrieval stay above it.

First-batch scope and non-goals

In scope:

• a library page with card and list views, folders and Unfiled, processing status, upload, rename, move, deletion after confirmation, and deleting empty folders;
• choosing materials from the composer, including @;
• agent tools;
• a one-line summary of each agent change in its tool-call row;
• configurable upload limits, with the current default of 50 MiB (52,428,800 bytes).

Material and course folders stay separate. Adding materials may use a dialog, and an original opens in a new tab or downloads.

Out of scope:

• an embedded reader, page thumbnails, search inside a document, reading guides, jumping to a cited passage, and resume-reading;
• notes, highlights and annotations;
• semantic retrieval, new indexing, and dedicated generation workflows (literal search remains available to the agent);
• nested folders, and sharing or transferring materials between owners;
• moving session-only fetch_url materials into the library;
• deletion or navigation by the agent;
• undo and result cards (§6), and links from the conversation to a folder;
• deleting a folder that is not empty (moving its contents back to Unfiled can follow);
• rewriting existing session material ids or existing course media.

Design

1. Upload is ingest

Uploading from the composer or from the library page creates a source material in Unfiled (folderId = null). A composer upload is also attached to the conversation. Choosing a material that is already in the library does not upload it again.

Shown as	Meaning
Uploading	The upload reservation has not finished
Stored · not parsed	The file is ready; extraction has not started
Parsing	Extraction is pending or running
Searchable	Extracted text is available
Parse failed	Extraction failed; the reason is shown

These labels map onto the existing status values. Extraction queueing, leases and completion, which today live on session materials, move to the owner level. The details belong in the Phase 1 PR.

Upload and extraction stay separate states, so a stored file is never assumed to be searchable. A message cannot be sent while any of its files is still uploading, and the composer and the page use the same ingest and admission rules.

2. Manifest, folders, pool and roots

The owner manifest records identity and organization. owner_material gains asset_id (the original in the pool), a nullable folder_id, a display_name separate from the original filename, the current extraction attempt and state, and a pointer to the latest completed extraction. Material ids stay globally unique.

Folders are stored as { owner_id, id, name, normalized_name, created_at, updated_at }, unique on owner and id and on owner and normalized name. They use the same name normalization as course folders. Unfiled is the absence of a folder, not a folder row. Images and audio tracks produced by extraction become owner material kinds linked by derivedFrom (§3).

Every retained file goes into the pool. Originals, extraction artifacts, readable text or transcripts, and derived media are allocated under assetPrincipalForOwner. Media embedded in a stored artifact is ingested separately and replaced by references to the allocated assets. Lineage (source, extractor version, and page or time when supplied) is recorded in the library, not in storage.

Reference roots keep materials alive. The proposed table is asset_root_refs(root_kind, root_id, asset_id), with a composite primary key, an index on asset_id, and a cascading foreign key to asset_entries. The library writes ('material', materialId, assetId) rows. Storage does not interpret root_kind, and because material ids are globally unique, root rows do not change when a claim moves the material.

Claims move the whole library. The owner-material claim participant is extended to folders and extraction metadata; the existing assets participant already re-keys asset principals. Folder conflicts follow the course-folder claim rules. Schema, locking and claim details belong in the Phase 1 PR.

Invariants

• Publishing a manifest change, changing root rows and updating lifecycle columns happen in one transaction under fenceOwnerWrite. The transaction keeps the existing sorted entry-lock order and checks that every asset exists and belongs to the same owner.
• Adding a root commits the entry and clears its expiry and unreferenced marks. Withdrawal, collector marking and backfill, and the final release check all look at both reference tables.
• The reference-tracking marker records the version of the reference rules its writers apply. A collector that finds a newer version than its own releases nothing, so a future kind of reference needs no manual rollout rule for collectors.
• Deleting a material marks the source and its derivatives as deleted, cancels pending work and withdraws their roots in one transaction. A referenced entry is never removed unconditionally; shared bytes are released only after the last reference and the grace period.
• A root keeps an asset alive but does not make it readable to other owners. Reading another owner's asset still requires a live course reference from that owner. Library assets cannot be changed through the generic replace or remove paths either, and a legacy shared entry that any root holds cannot be replaced or removed by anyone.
• An allocation that is never published expires. An uncertain commit outcome never triggers deletion of bytes that may already be committed.

3. Extraction and stable ids

Extraction becomes reusable owner-level state. extract_material keeps its "ensure extraction has started" semantics: idle and failed sources are queued; running and completed ones are left alone. wait_for_materials keeps its bounded-wait semantics and gains an optional library scope (§5). Changing the extractor does not re-run completed sources; forced re-extraction needs a future, explicit policy.

A source id reads its latest completed text. Today, reading a source returns source_requires_derivative, and extraction creates separate extraction or transcript materials with their own ids. Under this proposal, reading or searching by source id uses the latest successful extraction; if there is none yet, the call returns the extraction state and suggests extract_material.

Text and transcripts become artifacts of the source rather than separate visible materials; keeping internal derivative rows would also work (see the open question on storing extracted text). Media derivatives such as images and audio tracks keep their own ids, inherit the source's folder, and cannot be moved, renamed or deleted on their own; list_materials exposes their lineage and any page or time the extractor supplied. use_material_media accepts media source and derivative ids. Reading image or audio materials still returns unsupported-kind guidance.

The extraction cache is scoped per owner. Its key combines the owner, the content identity, the extractor id@version that actually ran, and any result-affecting options. A cross-owner hit would reveal that someone else uploaded the same file, so there is no cross-owner lookup. The cache does not keep assets alive; a cache entry whose assets no longer exist or are no longer retained is a miss. Details belong in the Phase 1 PR.

Invariants

• A completed extraction publishes the text pointer, lineage, derivatives and roots in one transaction, and a late worker cannot restore a material that was deleted or claimed.
• Reads and search hits carry the extraction revision. A read at a non-zero offset must pass the revision returned by the preceding read or search hit; if the revision has changed, the agent is told to start again rather than given text from the wrong version.

4. Conversations and courses

Conversations attach materials without copying them. A new link table holds unique (session_id, material_id) pairs. Composer upload, the paperclip picker and @ all attach the same way: a selection is attached when the message is sent (removing it before sending attaches nothing), and attaching the same material twice has no extra effect. The @ menu searches all folders, shows each material's name, folder and state, skips files still uploading, and marks attached materials as selected. A course pick keeps its current meaning as the course target for the turn.

After a linked material is deleted, later reads through the link fail, though text already in the conversation stays; the delete confirmation says so (see the open question on conversations after deletion).

The agent prompt follows source ids. sessionMaterialsPromptBlock is rewritten around one flow: extract, wait, then read with the same id; it also covers derivatives, library scope, the organizing tools, and that deletion is left to the teacher. Every consumer of material ids, including import_pptx, resolves both new links and old session rows.

Using a material in a course allocates a separate entry. use_material_media returns a newly allocated src under the principal of the owner of the writable stage. The document write then records it in document_asset_refs. This implements #1153 §6. Resolver and promotion details belong in the Phase 2 PR.

A course-use entry is always separate, even for the same owner, so deleting the source cannot break the course. Preparing media does not by itself create a course reference: an entry that is never written into a course expires. Physical deduplication still counts against logical quota.

5. Shared operations and tools

The page and the agent call one implementation. HTTP routes and runtime tools are thin adapters that resolve the owner. Deciding how to classify materials is left to the agent and skills. Listing the owner's library and reporting limits are new API responses, not the behavior of today's GET /api/materials.

Operation	Initial tool interface	Given to agent
List materials	list_materials({ scope?, folderId?, query? })	Yes
List folders	list_material_folders({ query? })	Yes
Create folder	create_material_folder({ name }) → { folderId, created }	Yes
Move sources	move_materials({ materialIds, folderId }); null means Unfiled	Yes
Rename	rename_material({ materialId, name }) / rename_material_folder({ folderId, name })	Yes
Store an owned asset	store_material({ assetId, name?, folderId? })	Not in the first batch
Extract	extract_material({ materialId, scope? })	Yes
Delete a source and its derivatives	delete_material({ materialId })	No; page only
Delete an empty folder	Page operation; refused while the folder holds materials	No; page only
Read	read_material({ materialId, offset?, scope?, revision? })	Yes
Literal search	search_material({ query, materialId?, scope? })	Yes
Wait	wait_for_materials({ materialIds?, timeoutSec?, scope? })	Yes
Use media	use_material_media({ materialId, stageId, scope? })	Yes

scope defaults to 'session'; 'library' reaches the owner's unattached materials. In library listings, omitting folderId lists everything and null lists Unfiled only; query filters by name and metadata. Uploads create their entry directly, without store_material. Paging and adapter details belong in the Phase 2 PR.

Every change goes through the owner write fence, and a move applies to all of its sources or to none. A library-scope wait must name its material ids. Literal search keeps its current limits and reports truncation. Creating a folder with an existing name returns that folder with created: false, and a move or rename that changes nothing reports that nothing changed.

6. Tool-row summaries

Each organizing or extraction call shows a one-line summary in its existing tool-call row, for example "Created folder 'Functions'", "Moved 2 materials to 'Functions'" or "Started parsing 2 materials". An extraction summary says whether work started, was already running, or had already completed. There is no custom card component and no link to a folder for now.

There is no undo in the first batch. Library changes are low-risk: the agent cannot delete, and every create, move or rename is easy to reverse by hand or by asking the agent. The first batch therefore has no operation records, revision counters or undo endpoint; undo can be added later if it turns out to be needed.

7. Navigation and refresh

The library page opens in the main area. It shows folders, card and list views, status, opening or downloading the original, and "chat with this material". Agent operations never change the folder the teacher is looking at.

During a run, material changes are reported through the existing library_changed event with a materials discriminator, and the client refetches. Extraction completes in the background, so outside a run the page also needs to pick up those results, as well as changes made in other tabs. Two options were considered, and the first batch uses B:

• A — Owner event stream. /api/agent/owner-events already streams durable session summaries with LISTEN/NOTIFY wakeups and a 30-second polling fallback. It would add a persisted library revision as an invalidation signal, reconciled on connect, reconnect, resync, degraded catch-up and claims; the library revision does not replace the session event replay cursor.
• B — Polling and focus refresh. The page refetches after its own changes, on focus, and periodically while uploads or extractions are pending. No new protocol is needed, but changes made elsewhere may not appear until the next refresh.

Refreshing never navigates. In option A, the library revision is committed together with each change, and NOTIFY is only a wakeup, never the source of truth.

8. Limits and quotas

Existing limits stay configurable and are shown before upload. The owner library listing returns the settings and current usage:

Setting	Default	Applies to
OPENMAIC_AGENT_MAX_UPLOAD_BYTES	50 MiB	All uploads; the per-file size ceiling for audio and video
MATERIALS_MAX_DOCUMENT_BYTES	50 MiB	Documents and images; the effective limit is the smaller of the two settings
MATERIALS_MAX_COUNT_PER_OWNER	100	Active source materials and upload reservations
MATERIALS_MAX_TOTAL_BYTES_PER_OWNER	2 GiB	Total bytes of sources and reservations
ASSET_QUOTA_BYTES	10 GiB; 0 disables it	The owner's live logical bytes in the pool

limits: {
  documentMaxBytes: number; mediaMaxBytes: number;
  maxCount: number; maxTotalBytes: number;
  usedCount: number; usedBytes: number;
  assetQuotaBytes: number | null; // null = disabled
  assetUsedBytes: number;
}

Both the source quotas and the pool quota are kept (see the open question on quotas).

Checks in the UI are early hints; the server remains the authority. Derivatives count toward the pool quota but not the source-count quota, so extraction can fail after a successful upload, and that failure is reported. Error responses keep their current codes (413 for size, 429 for source quota).

9. Compatibility and migration

Existing data stays readable until its migration commits. Ready uploads are migrated by a bounded backfill or on first access: allocate in the pool, publish the pointer and root, then remove the old bytes. Existing session materials keep their ids, copies and extraction rows, and a session can contain both old and new materials.

Schema, bootstrap, race handling and cleanup details belong in the Phase 1 PR; consumer compatibility belongs in the Phase 2 PR.

Two points matter for review. The DROP COLUMN asset_id statement in today's bootstrap must be removed, and an old process must not be able to run it again. Old bytes are removed only after the new pointer is confirmed, and nothing is deleted when a commit outcome is uncertain.

10. Naming

In the UI the feature is called Knowledge base (知识库 in Chinese); code and APIs keep material and material library. Since the first batch has no semantic Q&A, the empty state and onboarding say plainly what it does: upload teaching materials, have the assistant file and parse them, and pick them with @ while preparing a course.

Delivery phases

Every phase is its own PR to the integration branch integration/material-library, in this order, and each PR settles the details this RFC leaves open. The branch merges into main once, at the end.

Phase	Content	Rollout
1a	Manifest and folders; asset_root_refs and lifecycle checks against both reference tables; claims; the reference-rule version; removal of the DROP COLUMN asset_id bootstrap statement	Schema only; nothing writes roots yet
1b	Owner-level extraction state and the per-owner extraction cache	Service and tests only; new extraction output is not published until the Phase 2 readers exist
1c	New uploads into the pool, the pool-first read path, and the backfill of existing uploads, verified against a database with old sessions and new uploads side by side	First writes of material assets and roots
2	Tools and @: operations, tools and scopes; attachment resolvers; revision-aware reads; the new prompt; tool-row summaries; invalidation and limits; course copy-on-use; the composer picker and @; empty-folder deletion	Turn on complete producer and consumer paths; keep legacy reads
3	The library page and its left-rail entry; card and list views; limit display; refresh outside a run (option B); the empty state and onboarding; the control for deleting an empty folder	Completes navigation and freshness

Phase 2 lets the agent use the library before the page exists; no intermediate version links to a page that is not available yet.

Release conditions. Roots ship in the same release as 1a, and two hazards come from processes of an earlier release; the integration PR and the release notes state them:

• An older collector does not know about roots: its sweep stamps any committed entry no document references and releases it one grace period later. Upgrade all instances together and let the rollout finish well within ASSET_COLLECTION_GRACE_MS. Deployments that store users' original files may want a longer grace period than the one-hour default.
• An older bootstrap still runs DROP COLUMN IF EXISTS asset_id whenever it starts, which drops every pool pointer at once. Once any new instance has stored a material in the pool, no older instance may start against the database: stop the older instances before the new ones take writes.
• After the upgrade, never run an older version against the same database, and do not roll back below this release.

Decisions

Decided in this discussion:

• How to store extracted text: as artifacts owned by the source.
• Conversations after deletion: links stop working; text already in a conversation stays.
• Refresh outside a run: option B for the first batch; option A can follow if cross-device freshness turns out to matter.
• Quotas: the source quotas and the pool quota stay separate in the first batch.
• Deleting folders: empty folders can be deleted in the first batch; moving a deleted folder's contents back to Unfiled can wait.
• Without a database: hide the library.
• Undo and result cards: not in the first batch (§6).
• Upload phasing: new uploads go into the pool in 1c, together with the pool-first read path and the backfill, so no producer lands before its reader.
• Delivery: through integration/material-library, which merges into main once.
• Naming: Knowledge base / 知识库 in the UI (§10).

References

• Builds on: #1153 (parts #1154, #1164, #1168, #1172), #1669, Discussion #1657, #1658
• Storage history: #1242, #1472, #1473, #1524

Feedback from anyone is welcome, especially on the reference-root table (§2) and the phases.

[wyuc]

@LING-6150 Thanks — this is a solid RFC. Approving the overall direction; let's move to implementation.

The three sections you flagged

• §2 reference roots: Agreed. Keeping asset_root_refs generic (storage never interprets root_kind) is the right call, and it leaves room to fold course references into the same mechanism later. The transactional invariants, especially never deleting bytes when a commit outcome is uncertain, are exactly what this needs.
• §6 undo: Agreed, including server-side undo records keyed by (sessionId, toolCallId) and the revision counters. It is more machinery than a naive inverse, but undo is the safety net for the agent changing a teacher's data on its own, so it is worth doing properly.
• §7 refresh: Option B (refetch after own changes, on focus, and polling while uploads or extractions are pending) for the first batch. Option A can follow if cross-device freshness turns out to matter.

Open questions

• Extracted text: source-owned artifacts. Agreed.
• Conversations after deletion: links stop working, text already in the conversation stays. Agreed.
• Quotas: keep them separate in the first batch. Agreed.
• Deleting folders: please include deleting empty folders in the first batch. Being able to create folders but not remove them will feel broken, and the empty-only rule keeps it small. Moving contents back to Unfiled can wait.
• Without a database: hide the library. Agreed.

Next step: PRs

Please go ahead with one PR per phase against main, in the order of the delivery table. Phase 1 is the riskiest (schema, pool roots, claims, extraction cache and migration, including removing the DROP COLUMN asset_id bootstrap statement), so please split it further, for example:

1. manifest, folders and asset_root_refs with the lifecycle checks and claims;
2. owner-level extraction state and the per-owner cache;
3. backfill / migration of existing uploads.

For the migration PR, include a real run against a database with existing materials (old sessions plus new uploads side by side) in the PR description, not just unit tests. Keep each PR reviewable on its own and link them back to this discussion.

[LING-6150]

@wyuc Thanks! Tracking issue: THU-MAIC/OpenMAIC#1736.

Noted on all points. Empty-folder deletion is now in the first batch (page-only, in Phase 2, with the UI in Phase 4), and Phase 1 is split into 1a (manifest, folders, asset_root_refs, lifecycle checks and claims, including removing the DROP COLUMN asset_id bootstrap statement), 1b (owner-level extraction and cache) and 1c (migration, with a real run against a database that has old sessions and new uploads side by side). Each PR will link back here. Starting with 1a.

One question for 1a: I plan to keep 1a to schema, roots and lifecycle checks only, and start writing new uploads into the pool in 1c together with the pool-first read path and the backfill, so no producer lands before its reader. Does that split work for you?

[LING-6150]

@wyuc Two more points before 1a, from the code survey:

Undo records. PR 2 will commit each agent mutation together with its operation record (old values and revisions, keyed by (sessionId, toolCallId)), and PR 3 adds undo execution and result cards on top. Otherwise the organizing tools would ship in PR 2 with no reliable record to undo from. Revision counters therefore move from Phase 1 to PR 2.
Deployment constraints. Once a release writes material roots, pre-1a processes must be gone, because their collector does not know about roots and would reclaim root-only assets; rollback below 1a is no longer safe from then on. Once a release stores material bytes only in the pool, rollback below that release is not safe for reads either. The DROP COLUMN asset_id concern is covered by the first constraint, so it can only be enforced operationally, not in code. I will spell both out in the 1a PR description and again in the PR that first writes roots.
Neither point changes 1a's scope, so I am going ahead with 1a in the meantime.

[wyuc]

@LING-6150 Thanks for the follow-ups. Decisions on everything open, plus two scope cuts:

1. 1a stays schema-only. Agreed: 1a adds the schema, asset_root_refs and the collector checks, and nothing writes roots yet. New uploads go into the pool in 1c, together with the pool-first read path and the backfill, so no producer lands before its reader.

2. No undo and no result cards in the first batch. Library changes are low-risk (the agent cannot delete, and every create/move/rename is easy to reverse by hand or by asking the agent), so undo is not worth its cost right now. That removes the operation records and revision counters from PR 2 and drops Phase 3 entirely. Agent changes are shown through the existing tool-call rows, with a clear one-line summary per tool (e.g. "Created folder 'Functions'", "Moved 2 materials to 'Functions'", "Started parsing 2 materials"). No custom card component and no folder links for now. Please update the RFC body and the phases in #1736: 1a / 1b / 1c → tools and @ (with tool-row summaries and empty-folder deletion) → library page.

3. Land everything through an integration branch. Please create integration/material-library, retarget #1745 and #1753 to it, and send every later phase there. The branch merges into main once, at the end. Inside the branch, keep the 1a → 1c order.

I checked your deployment concern against the collector: you are right. A pre-1a collector's unreferenced sweep stamps any committed entry with no document_asset_refs row, then releases it after the grace period, so root-only entries are at risk from old processes. Since roots now ship in the same release as 1a, please state these release conditions in the integration PR and in the release notes:

• Upgrade all instances together and let the rollout finish well within ASSET_COLLECTION_GRACE_MS. An old collector needs at least one grace period between stamping and releasing an entry.
• After the upgrade, never run an older version against the same database, and do not roll back below this release.
• Deployments that store users' original files may want a longer grace period than the 1-hour default.

Also, in 1a please record a reference-rule version in the database and have the collector skip its entry level when the database's version is newer than the one it knows. It cannot protect this cutover, because old collectors do not know the check, but it means the next new reference kind will not need the same manual rule.

4. Naming. In the UI the feature is called Knowledge base (知识库 in Chinese). Code and APIs keep material / material library. Since the first batch has no semantic Q&A, the empty state and onboarding should say plainly what it does: upload teaching materials, have the assistant file and parse them, and pick them with @ while preparing a course.

5. Review. A review of #1745 is on its way. Please keep it open against the integration branch while that runs.

[wyuc]

@LING-6150 I've created integration/material-library from main (8f7d51e) and retargeted #1745 to it. Please keep #1753 stacked on the 1a branch for now; once 1a merges into the integration branch, retarget it there if GitHub doesn't do it automatically. All later phases should target the integration branch.

[LING-6150]

@wyuc Thanks, all noted. Update:

• RFC and [RFC] Material library (tracking) #1736 now follow the new plan: no undo or result cards in the first batch (Phase 3 removed, no operation records or revision counters in PR 2), phases 1a / 1b / 1c → tools and @ (with tool-row summaries and empty-folder deletion) → library page, delivered through integration/material-library. In the UI the feature is called Knowledge base / 知识库; code and APIs keep "material".
• 1a (feat(storage): add asset reference roots and the material library schema (1a) #1745): the review fixes are pushed (56f9be2). Rooted shared entries can no longer be replaced or removed, and the reference-rule version is recorded on the tracking marker; the collector refuses its entry level when the database's version is newer, including when it changes mid-pass. The release conditions are in the CHANGELOG, plus one more boundary: older bootstraps still drop owner_material.asset_id, so no older instance may start once a new one has stored a pool pointer. Details are in the PR.
• 1b (feat(persistence): owner-level material extraction state and per-owner cache (1b) #1753) is a draft stacked on 1a. I'll retarget it to the integration branch once 1a merges.
• 1c will start new uploads in the pool, together with the pool-first read path and the backfill, as agreed.

[LING-6150]

Update: 1c is open as a draft: THU-MAIC/OpenMAIC#1763 · feat(materials): store uploads… (stacked on #1753). It is the first phase that writes material roots; the deployment boundaries and the backfill switch are in its description. One question : will integration/material-library be deployed anywhere before it merges into main? @wyuc

[wyuc]

@LING-6150 Thanks — great follow-up on the old-bootstrap boundary.

• Deployment: no. integration/material-library will not be deployed anywhere on its own. It merges into main once all phases are done and ships as one release, so the release conditions (stop all older instances before new ones take writes, no rollback below the release) apply to that release only.
• CI: storage-pg-contract.yml now also triggers on PRs into the integration branch (0ff26fd), so the PostgreSQL contract runs for 1a/1b/1c from now on. Since 1a's base already moved, feat(storage): add asset reference roots and the material library schema (1a) #1745 will get a fresh run after a reopen.
• 1a: the incremental fix (56f9be2) is getting a quick review now; if it's clean I'll approve and merge 1a into the integration branch, then please retarget feat(persistence): owner-level material extraction state and per-owner cache (1b) #1753.

[LING-6150]

Update: Phase 1a (#1745), 1b (#1753), and 1c (#1763) are merged into integration/material-library. The three required follow-ups from the 1c review are also merged in #1791: losing backfill allocations are cleaned up, failed pool reads can fall back to retained old objects, and old-object reads verify the recorded digest.

@wyuc

I'm preparing Phase 2 as one PR, following the current RFC. Owner extraction will be enabled only when the complete producer/consumer paths, including document-image ingestion and reference rewriting, are ready.

One delivery-boundary question: §5 includes source deletion as a shared, page-only operation, but the delivery table explicitly names only empty-folder deletion/control.

I propose delivering the shared source-deletion operation and HTTP route in Phase 2, with the confirmation UI in Phase 3. Phase 2 would therefore cover the real deletion transaction and late-worker concurrency tests.

Does that match the intended boundary? If all source-deletion functionality should instead ship in Phase 3, Phase 2 will test deleted-row rejection only, and the real deletion transaction tests will ship with Phase 3.

[wyuc]

@LING-6150 Answered on #1792. In short: source deletion ships as its own small PR into the integration branch after Phase 2, as option A with a focused review and a real run, with the confirmation control in Phase 3. Phase 2 is split after commit 6 into two stacked PRs. All scope decisions are accepted.