Test / Tests and coverage occurred while executing withChecks step.
Intrepid/AI Engineering/pipeline/head There was a failure building this commit
build / jvm (push) Canceled after 0s
build / native (macos-15, macos-arm64) (push) Canceled after 0s
build / native (ubuntu-24.04, linux-x86_64) (push) Canceled after 0s
build / native (windows-2025, windows-x86_64) (push) Canceled after 0s
Add deterministic preview and fingerprint-bound application for independent DF sources under an AIE umbrella. Preserve complete agendas and original evidence with source-scoped identities, validated receipts and safe retries. Publish prepared Works atomically, require review for changed imports and retain existing refinement without source edits or model calls. Advertise protocol contract 2 while continuing to read contract-1 projects. Add JVM, concurrency, recovery and native coverage; document usage and complete WRK-0007 with verification evidence.
95 lines
5.5 KiB
Markdown
95 lines
5.5 KiB
Markdown
# Discussion Framework import
|
|
|
|
Import DSC discussions with open AGD agendas into the current AIE project. Each
|
|
source is an independent DF tree; the destination may be a plain project or an
|
|
umbrella containing several such projects. No model, source mutation, repository
|
|
registration, imported decision or imported execution plan is involved.
|
|
|
|
## Commands
|
|
|
|
This capability is advertised by protocol contract 2. The updated CLI also reads
|
|
contract 1 projects and historical Work formats; no Work conversion is required.
|
|
`onboard` refreshes entry instructions with backups after compatibility inspection.
|
|
Older contract-1 CLIs refuse a contract-2 manifest instead of overwriting it.
|
|
|
|
```sh
|
|
aie import discussion --source runtime=../runtime --source studio=../studio \
|
|
--target runtime=runtime --target runtime=docs --target studio=studio --format json
|
|
aie import discussion --source runtime=../runtime --source studio=../studio \
|
|
--target runtime=runtime --target runtime=docs --target studio=studio \
|
|
--apply --expect <preview-fingerprint> --author owner --format json
|
|
```
|
|
|
|
`--source ID=PATH` is repeatable and required. IDs follow AIE project identifier
|
|
rules and must remain stable across imports; paths resolve relative to the caller,
|
|
including when `--project` selects a different destination. A path may name the
|
|
source project or its existing `discussion/` directory. Duplicate IDs or roots in
|
|
one request are rejected. Source locations may move while keeping their identity.
|
|
|
|
`--target SOURCE=TEXT` is repeatable. Targets are authored descriptions recorded
|
|
in the imported Work; they do not register or authorize repository edits. Without
|
|
an explicit target, the caller-supplied source ID identifies the project target.
|
|
|
|
Without `--apply`, the command is read-only, including no destination locks or
|
|
backups. It reports each DSC, selected/ignored agendas, source paths and hashes,
|
|
existing Work, and an action: CREATE, UNCHANGED, REVIEW or SKIP. Invalid inputs
|
|
are diagnosed in the report. REVIEW and errors block the selected batch.
|
|
|
|
`--apply` requires `--expect` from a valid preview. The sources and destination
|
|
import identities are read again under the destination lock; a changed preview
|
|
fingerprint is refused before allocation or publication. Publication rechecks the
|
|
captured source bytes before writing any Works. There is no automatic override
|
|
of REVIEW items; refine the inputs or review the existing Work explicitly.
|
|
|
|
## Selection and preservation
|
|
|
|
Read `discussion/index.ndjson`: first record `type=meta`, subsequent records
|
|
`type=discussion`. Select each DSC with at least one indexed AGD whose exact
|
|
status is `open`. Other nonblank states are ignored with a reason. The DSC's
|
|
aggregate status is not a substitute for the agenda status. An absent DEC is
|
|
normal. Historical closed agendas need not have files when they are not selected.
|
|
|
|
Selected agenda files must have front matter whose ID and status agree with the
|
|
index. Missing/ambiguous references, duplicate DSC/AGD identities in one source,
|
|
invalid UTF-8, escaping paths, symlinked descendants or inconsistent selected data
|
|
block application. Unknown source metadata is retained in the original DSC record,
|
|
not inferred into new AIE semantics. The DF validator alone is not sufficient.
|
|
|
|
One OPEN Work is created per source ID + DSC ID. Each selected AGD becomes a NOTE
|
|
in refinement with its complete original Markdown text, not a summary or parsed
|
|
set of human answers. Original agenda bytes and the original DSC index record
|
|
are owned ART evidence. A versioned import receipt, also owned evidence, links
|
|
source identity, DSC and AGD IDs, source hashes, targets, discussion IDs and ART IDs.
|
|
The source directory is an audit location, not the sole import identity.
|
|
|
|
Limits: an index is at most 8 MiB, individual selected agendas and evidence are at
|
|
most 1 MiB, and captured source data per request is at most 32 MiB. Oversized data
|
|
is reported before publication. These are explicit limits, never truncation.
|
|
|
|
## Reimport and failure recovery
|
|
|
|
The same source ID + DSC with identical content and targets is UNCHANGED. It does
|
|
not add or rewrite Works, notes or evidence, including when the Work has since
|
|
been refined, completed or archived. New or changed source content for an existing
|
|
identity is REVIEW. No destination content is overwritten or deleted; a changed
|
|
agenda state never removes previously imported context.
|
|
|
|
A Work and all its initial records are built in the existing hidden Work staging
|
|
area and published by one directory move using the normal Work ID sequence.
|
|
Readers do not see a half-seeded Work. A batch is not a global transaction:
|
|
an I/O failure or process interruption after one Work is published may leave that
|
|
Work imported. The error identifies published Works; a fresh preview recognizes
|
|
them as UNCHANGED and can continue the remaining items without duplication.
|
|
Unpublished hidden staging folders and reserved ID gaps may remain for deliberate
|
|
inspection; neither is interpreted as an imported discussion.
|
|
|
|
Preview, apply and validation verify owned receipt integrity and references.
|
|
Refinement prose may evolve in the destination while the original evidence remains
|
|
intact. Conflicting import identities or corrupted receipts must be repaired
|
|
explicitly; no receipt, original evidence or historical Work is silently rewritten.
|
|
|
|
Exit codes follow AIE: 0 for a valid preview/application, 2 for invalid command
|
|
arguments, 3 for a missing project/root, 4 for invalid/stale/review-required data,
|
|
and 1 for unexpected I/O failures. Diagnostics after partial publication retain
|
|
the normal failure code and identify the Work IDs already published.
|