​

Research and Generation

This is the canonical contract for moving from user-provided order data to a validated notebook. It separates five concerns that must never be collapsed into one boolean: recorded input, strain identity, research readiness, generation lifecycle, and publication state.

​

End-to-end data flow

​

1. Preserve the recorded order

The order record is the user’s source of truth. Save every line and retain stable line identity across manual text, image parsing, Gmail import, review edits, research callbacks, and notebook generation. Required behavior:

• Missing price, dispensary, quantity detail, or strain type remains missing.
• Duplicate lines remain individually traceable.
• Mixed units are normalized only by an explicit deterministic rule.
• A valid order can contain zero matched strains.
• Queue acceptance must not change an order line to “researched” or “resolved.”
• A later exact research result may enrich the same line; it must not create a duplicate stash projection.

​

2. Resolve strain identity honestly

Do not use a weak “first search result” fallback. A wrong match is worse than an explicit unknown because it contaminates lessons, evidence, updates, and the long-term strain database.

​

3. Track research readiness and conflict separately

The readiness contract is: Source conflict is separate metadata. A revision can be fresh and still contain a documented source disagreement.

​

New strain behavior

When an order contains a strain that is not in the database:

1. Save the order line as unknown with its exact recorded name.
2. Create or reuse a stable research subject identity; do not bind by display-name search result.
3. Attempt a bounded claim only after the research engine is safely activated.
4. Record leased, cooldown, fresh-skip, no-data, failed, canceled, and success outcomes distinctly.
5. On success, atomically publish the immutable research revision and update the current research pointer.
6. Notify the exact waiting order item/run pair.
7. Create the stash projection exactly once if product policy allows it.
8. Never publish synthetic catalog stubs for a no-data result.

​

4. Freeze evidence for the notebook

Report V2 freezes a minimized canonical source snapshot for each attempt. The snapshot should contain:

• recorded order or selected-stash facts required by the notebook;
• stable order-item/source identifiers;
• the exact immutable research revision used for each subject;
• bounded canonical source URLs and retrieval checksums;
• explicit unavailable/conflict/quality metadata;
• no email body, account token, provider payload, address, phone number, or unrelated profile field.

Every generated claim must resolve to recorded evidence or research evidence in that snapshot. If it cannot, withhold it or mark the lesson unavailable.

​

5. Generate with recoverable lifecycle state

UI rules:

• Minimize or swipe-down closes the progress sheet but keeps the server task running.
• The tab-bar accessory can reopen active progress.
• Dismissal is scoped to one attempt and must not cancel it.
• Cancellation requires confirmation and shows requesting, pending, confirmed, failed, or too-late state.
• Missing numeric progress uses an indeterminate presentation; never invent a percentage or ETA.
• If a readable publication exists, keep it available throughout an update.

​

6. Publish immutable versions

A validated Report V2 promotion must atomically:

1. insert an immutable child publication;
2. bind it to the exact attempt, snapshot, artifact manifest, and payload checksum;
3. advance the notebook’s current publication pointer;
4. update the denormalized current reader cache;
5. leave every prior publication unchanged and owner-readable.

Failed, canceled, abandoned, superseded, malformed, or ambiguous candidates never replace the current publication.

​

Update journey

Automatic freshness detection and the customer update request are still disabled. Studio models the entire journey so the contract can be certified before activation.

​

Safe activation blockers

Before importing the lazy coordinators into live research engines, resolve and test:

• terminalize failures only after Trigger retry exhaustion;
• define behavior for leased, cooldown, skipped-fresh, and terminal duplicate dispositions without firing premature success callbacks;
• make the legacy “catalog row exists” shortcut revision-mode aware;
• preserve stable per-subject run identity across reordered and partial batches;
• settle or recover every claimed lease after partial begin failure;
• route direct, Batch API, bulk, and scheduled entry points through the same fenced contract;
• prove that no subject can publish another subject’s evidence in a partial batch.

Then follow the exact order in Notebook launch runbook.

​

Verification map

​

Related documentation

• Notebook program overview
• Notebook Studio
• Notebook launch runbook
• Customer generation explanation