Merge remote-tracking branch 'origin/main'
# Conflicts: # mkdocs.yml
This commit is contained in:
Codex
@@ -0,0 +1,59 @@
|
||||
---
|
||||
status: accepted
|
||||
date: 2026-09-08
|
||||
---
|
||||
|
||||
# Use PostgreSQL for Memory and Qdrant for retrieval
|
||||
|
||||
The new Memory module uses the installation's existing PostgreSQL service as the
|
||||
authority for Memory Cards, their links, and structured schema dependencies.
|
||||
Qdrant holds a rebuildable search projection. This replaces the JSONL registry and
|
||||
allows related administrative changes to be coordinated in one database transaction.
|
||||
The owner accepted this direction in Q9 of the Memory design interview; implementation
|
||||
is pending.
|
||||
|
||||
Memory uses its own tables and remains a separate module from the Metadata Catalog.
|
||||
Sharing the PostgreSQL service does not transfer Memory ownership to Database
|
||||
management or make Evidence and Memory one canonical domain.
|
||||
|
||||
## Retrieval and graph
|
||||
|
||||
The owner also accepted hybrid semantic/lexical Qdrant retrieval with scope filters
|
||||
and explicit card links traversed in core. Both belong to the planned first version;
|
||||
there is no dedicated graph database or external Memory framework.
|
||||
|
||||
This extends [ADR 0017](0017-separate-reference-vectors-from-runtime-memory.md):
|
||||
the separate reference and memory collections remain, while Memory gains sparse
|
||||
lexical indexing in addition to dense vectors. Memory projections become rebuildable
|
||||
from the module's PostgreSQL authority. Preprocessing Clear still preserves Memory;
|
||||
this decision does not add it to the preprocessing cleanup scope.
|
||||
|
||||
Links support discovery. Finding a card through a link does not approve its use.
|
||||
The core proposes links with the cards for the same final review; Administration
|
||||
provides manual creation, editing, and deletion. Deleting a card removes its incident
|
||||
links without deleting the other linked cards.
|
||||
|
||||
## Considered options
|
||||
|
||||
- Retaining JSONL preserves the current storage format, but leaves coordinated
|
||||
card/link/dependency mutations and concurrent administrative writes to application code.
|
||||
- Using Qdrant as the sole authority is a viable alternative for record storage and
|
||||
retrieval. PostgreSQL is preferred for the coordinated mutations of the new module,
|
||||
with Qdrant reserved for its search projection.
|
||||
- Adding a dedicated graph database would introduce another service; the selected
|
||||
bounded traversal can be implemented in core over persisted links.
|
||||
|
||||
## Consequences
|
||||
|
||||
The module needs a persistence contract, PostgreSQL schema, and explicit propagation
|
||||
of additions, updates, and deletions to Qdrant. Choosing PostgreSQL does not make this
|
||||
propagation atomic across both systems: failures, retries, and invalidation of stale
|
||||
search content must be handled and tested. An index rebuild uses the original card
|
||||
content and cannot resurrect deleted cards.
|
||||
|
||||
The decision does not introduce Memory revision history or require compatibility with
|
||||
existing development sessions. Evidence authoring and publication remain governed by
|
||||
their own contract until the Evidence management project defines its evolution.
|
||||
|
||||
The [Memory management project](../plans/2026-09-08-memory-management.md) records the
|
||||
approved behavior, scope, and integration work.
|
||||
@@ -0,0 +1,152 @@
|
||||
---
|
||||
status: accepted
|
||||
date: 2026-09-08
|
||||
---
|
||||
|
||||
# Maintain local Evidence with external editors and manual consolidation
|
||||
|
||||
Evidence management must provide complete access to registered Evidence and a
|
||||
maintenance path, as accepted in Q11–Q15 and revised during simplification. The owner subsequently
|
||||
clarified that a context specialist writes drafts independently of the installation
|
||||
and without PostgreSQL access; the system refines and stores them locally for use
|
||||
and maintenance. Implementation is pending.
|
||||
|
||||
The storage mechanics of Q11 were revisited in the
|
||||
[simplification review](../plans/2026-09-08-memory-evidence-simplification-review.md).
|
||||
The original choice combined the workspace repository as Evidence authority with
|
||||
application-managed Git writes. The owner accepted the separation of external draft
|
||||
files/repositories from a durable local canonical file archive and removes
|
||||
commit/push from normal CRUD. The management surface must expose discoverable,
|
||||
editable Markdown for domain specialists, without JSONL editing. The owner chose
|
||||
external editors for release 0: their preferred Mac/PC editor or vim/nano on the
|
||||
server. No web editor or content form is required. The page keeps browsing,
|
||||
filtering, and detail, with actual host file paths and maintenance instructions.
|
||||
The owner also requested manual consolidation followed by manual Git diff, commit,
|
||||
and push, relying on operator discipline rather than automation. The owner accepted
|
||||
the remaining simplifications and requested explicit clarification of the core
|
||||
format change and the simple terminal-based Git check. The original application Git writer
|
||||
is not the final implementation prescription. A suggestion
|
||||
to move Evidence authority into PostgreSQL was withdrawn after the clarification.
|
||||
Memory remains a distinct module with its own PostgreSQL authority under
|
||||
[ADR 0018](0018-use-postgres-for-memory-and-qdrant-for-retrieval.md).
|
||||
|
||||
## Manual consolidation and Git follow-up
|
||||
|
||||
The external-editor decision replaces the form's single Save with saving files and
|
||||
running one consolidation command. The command checks expected structure, required
|
||||
fields, types, identifiers, references, and provenance. It reports the affected file
|
||||
and the necessary correction. Invalid input stops activation; valid input updates
|
||||
derived metadata, the corpus, and the Evidence index. New and deleted files use the
|
||||
same path. An inaccessible archive must not be interpreted as deleted Evidence.
|
||||
Structural validation does not prove semantic correctness or rerun model refinement
|
||||
to rewrite manually edited rules.
|
||||
|
||||
The core reads only successfully consolidated active content, never the editable
|
||||
working files directly. Candidate validation and activation must preserve the last
|
||||
valid corpus on failure, or report unavailability if its integrity cannot be
|
||||
guaranteed. Unconsolidated edits must not mix new text with old retrieval data.
|
||||
|
||||
Consolidation reports full local success only once the updated content is available
|
||||
to the core. If persistence succeeds but activation fails, the command reports the
|
||||
partial outcome and can be rerun without duplicating units or losing edits.
|
||||
The operation does not imply atomicity across
|
||||
authoritative storage and Qdrant; their failure and recovery behavior requires
|
||||
explicit implementation. An interrupted operation must not leave a partial corpus
|
||||
advertised as ready for subsequent use.
|
||||
|
||||
The maintained archive is a persistent Git working tree containing the local
|
||||
Evidence; it may reuse the workspace repository. Draft sources and curated units
|
||||
remain distinct even when in the same repository. Setup and the page identify the
|
||||
repository, working tree, actual host paths, branch, and configured remote. A
|
||||
rebuildable runtime snapshot is not the editing location.
|
||||
|
||||
Before consolidation, the operator checks Git status, including inspection of new
|
||||
untracked files. Normal terminal Git diff commands are available for line-level
|
||||
inspection when needed; no custom viewer or mandatory double review is required.
|
||||
After consolidation, the operator stages the Evidence and required metadata changes,
|
||||
commits, and pushes using normal Git commands. No watcher, automatic Git writes, retrying push, pull, merge,
|
||||
or dedicated web execution control is required. Missing credentials, unconfigured
|
||||
upstreams, and Git conflicts are handled by the operator.
|
||||
|
||||
Consolidation activates local changes before commit/push. If the operator omits the
|
||||
Git steps or push fails, the local update remains effective while transfer to the
|
||||
remote is incomplete. Pushing does not automatically update other installations.
|
||||
The system relies on operator discipline to complete the sequence; it does not add
|
||||
a separate editorial publication state machine or require a second reviewer.
|
||||
|
||||
Approved conflict repairs from the core still call the same persistence and
|
||||
activation service directly. They do not require an external editor or manual
|
||||
consolidation before the session can use its own approved correction. Their local
|
||||
file changes are included in the operator's subsequent Git maintenance.
|
||||
|
||||
## Administration without concurrent core work
|
||||
|
||||
The owner's simplification instruction replaces the earlier Q12 requirement to
|
||||
refresh open sessions after administrative edits. Core activity can be assumed
|
||||
absent during administration, or its overlap can be ignored. No dedicated live
|
||||
update, session notification, restart, maintenance mode, or reader coordination
|
||||
is required. Completed administrative changes apply to subsequent work.
|
||||
|
||||
Deliberate writes from the workflow itself still exist: approved conflict repairs
|
||||
and the final Memory summary use the same persistence services and handle their
|
||||
outcome before proceeding. In particular, a session must be able to use its own
|
||||
approved Evidence correction. This does not require updating all other sessions
|
||||
or rewriting previously approved decisions, artifacts, or SQL.
|
||||
|
||||
## Manual corrections survive source updates
|
||||
|
||||
When an updated source contradicts an administrator's correction, the saved manual
|
||||
Evidence remains active. Evidence management shows the conflicting content for an
|
||||
explicit decision and subsequent save. The source's newer content does not
|
||||
automatically override the correction. The owner accepts that the manual rule can
|
||||
remain in use until that comparison is resolved.
|
||||
|
||||
Deleted Evidence must not silently reappear after preparation or reindexing. The
|
||||
authoring implementation must preserve both manual corrections and suppression of
|
||||
deleted units through source refreshes. The current protection for uncommitted Git
|
||||
changes is insufficient: it does not preserve already committed manual corrections
|
||||
against regeneration, and retirement currently removes the unit without recording
|
||||
suppression for later preparation.
|
||||
|
||||
## Manual creation and explicit source refresh
|
||||
|
||||
Administrators can create Evidence without providing an external document. In R0,
|
||||
they add Markdown using the documented example and consolidate it. The application
|
||||
records a manual declaration as the managed source of the current statement.
|
||||
Explicit consolidation approves that declaration; it does not
|
||||
claim independent documentary verification.
|
||||
|
||||
A correction that changes a unit's meaning uses the same explicit manual origin.
|
||||
The original document remains linked for provenance and source-change detection,
|
||||
but its excerpt is not presented as support for a rule it does not contain. The
|
||||
canonical contract must distinguish the current supporting source from the original
|
||||
document rather than silently retaining outdated support metadata.
|
||||
|
||||
External sources are reacquired only when an administrator requests a source
|
||||
refresh. Ordinary saves and session lookups use the acquired local content; they
|
||||
do not poll sources or fetch their current versions. A remote change is therefore
|
||||
detected at the next requested refresh, when the manual-precedence rule applies.
|
||||
The revised storage recommendation reads the specialist's repository as an input;
|
||||
ordinary local edits do not write back to it or refresh its content automatically.
|
||||
|
||||
## Implementation consequences
|
||||
|
||||
The existing [Evidence lifecycle](../evidence.md) and
|
||||
[Workspace Evidence v3 contract](../contracts/workspace-evidence-v3.md) require
|
||||
explicit evolution for editable local Markdown, manual consolidation, and manual
|
||||
precedence. Source provenance and coherent canonical metadata remain requirements;
|
||||
manual changes must not be presented as statements supported by an unrelated source
|
||||
excerpt. Under the accepted local-file direction, curated files are primary
|
||||
installation data preserved by Clear and backed up separately from rebuildable
|
||||
indexes. Visible Markdown content must become authoritative for editing; operators
|
||||
must not maintain hidden duplicate text, hashes, or manifest entries themselves.
|
||||
This is a core Evidence contract change: parser, renderer, authoring, validation,
|
||||
normalization, and their integration with indexing and recall must be adapted
|
||||
together. E1 includes a new Curated unit format version, conversion of existing
|
||||
Evidence, reindexing, and end-to-end verification that visible edits reach core
|
||||
consumption. Preserve the internal typed model where possible; the change does
|
||||
not require redesigning the NL-to-SQL workflow phases.
|
||||
Local edits do not automatically change external drafts or another installation;
|
||||
Git versioning and transfer occur through the explicit manual follow-up.
|
||||
The [Evidence management project](../plans/2026-09-08-evidence-management.md)
|
||||
records the implementation sequence and acceptance checks.
|
||||
@@ -33,11 +33,16 @@ The production role expansion from `backend/src/auth/config.ts` is exact:
|
||||
| Role | Permissions |
|
||||
|---|---|
|
||||
| `user` | `session.use` |
|
||||
| `admin` | `session.use`, `session.read_all`, `session.manage_all`, `settings.manage`, `workspace.manage`, `workspace.secrets.manage`, `database.manage`, `pi.manage`, `auth.diagnostics.read` |
|
||||
| `admin` | `session.use`, `session.read_all`, `session.manage_all`, `settings.manage`, `workspace.manage`, `workspace.secrets.manage`, `database.manage`, `memory.manage`, `evidence.manage`, `pi.manage`, `auth.diagnostics.read` |
|
||||
|
||||
`admin` therefore includes the ordinary `session.use` permission. No other role or permission
|
||||
label is part of the production catalog.
|
||||
|
||||
After validating a browser session, the backend expands its roles through the current permission
|
||||
catalog on every request. The permissions saved at login are a historical snapshot, so existing
|
||||
administrator sessions can use newly deployed administration features without signing in again.
|
||||
Session expiry, revocation and local-user role validation still apply before role expansion.
|
||||
|
||||
OIDC is provider-neutral at the browser protocol boundary. Authorization Code + PKCE, issuer,
|
||||
signature, audience, expiry, state, and nonce are validated before a principal is created.
|
||||
Authentik is the first certified group-catalog adapter, not a special browser login mode.
|
||||
|
||||
@@ -7,7 +7,9 @@ This page complements the [architecture overview](overview.md) with the module s
|
||||
The frontend communicates with the backend through REST and SSE. The backend does not own session
|
||||
persistence: it starts Pi, invokes the `tht` CLI, and forwards events. It does own the separate
|
||||
installation-local database catalog. The harness contains the workflow, the Python CLI, and
|
||||
adapters for the DWH and vector store.
|
||||
adapters for the DWH and vector store. Its Memory module also owns the authoritative
|
||||
PostgreSQL archive of cards, links, dependencies and pending Qdrant projections.
|
||||
Administrative API calls use the same harness service as workflow producers and recall.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
@@ -20,6 +22,7 @@ flowchart LR
|
||||
THT --> FS["Sessions and artifacts\nworkspace repository"]
|
||||
THT --> DWH["DWH\nread-only"]
|
||||
THT --> VDB["Qdrant / vector store"]
|
||||
THT --> MEM["thoth_memory\nPostgreSQL Memory archive"]
|
||||
BE --> CFG["settings.json\nworkspace + thinking"]
|
||||
BE --> MODELS["generated runtime catalog\nfrom installation YAML"]
|
||||
BE --> CAT["catalog-db\nPostgreSQL + Kysely"]
|
||||
|
||||
@@ -0,0 +1,65 @@
|
||||
# Session corrections to Memory and Evidence
|
||||
|
||||
`reviewer_archive_repair` presents one to five closed alternatives for a conflict.
|
||||
Each alternative updates one existing Memory Card or one existing local Evidence unit,
|
||||
showing complete current and resulting content. The reviewer chooses one alternative,
|
||||
rejects all as inadequate, or asks for reformulation. A correction does not approve or
|
||||
advance the session phase; the ordinary gate still reviews its use in the current question.
|
||||
|
||||
The harness coordinator `tht/archive_repair.py` joins two independent domains. It uses
|
||||
Memory's PostgreSQL repository, workspace mutation lock and projection service, and the
|
||||
same local Evidence save/consolidation boundary as administration. Evidence activation
|
||||
runs the existing corpus pipeline without reacquiring configured external sources.
|
||||
No database binding, schema configuration, other archive, or Git repository is changed.
|
||||
|
||||
## Authority and recovery
|
||||
|
||||
Migration `004_archive_repairs.sql` stores session-bound proposals and receipts in
|
||||
`thoth_memory.archive_repairs`, isolated by workspace RLS. Each receipt captures the
|
||||
session decision context, current target revision, complete resulting content, selected
|
||||
choice, acting principal and publication outcome. The preparation command changes no
|
||||
archive content. Application accepts only an option ID from the persisted proposal.
|
||||
|
||||
Memory writes its new revision and receipt in one SQL transaction. Projection failures
|
||||
leave a durable pending operation; retry propagates the saved revision. A later card
|
||||
edit invalidates replay of the correction.
|
||||
|
||||
Evidence records the exact choice before writing its canonical file. Recovery accepts
|
||||
either the reviewed original revision or the already-written approved result; it never
|
||||
overwrites a different intervening correction. Before a first proposal, the editable
|
||||
checkout must match its active snapshot. Other curated files are fingerprinted and
|
||||
checked again before application/retry so a session decision cannot publish unrelated
|
||||
external edits. A crash after replacement is recoverable by the same receipt. Original
|
||||
document provenance is retained as the lineage of the manual correction.
|
||||
|
||||
The gate displays these outcomes:
|
||||
|
||||
| Status | Meaning |
|
||||
| --- | --- |
|
||||
| `proposed` | Waiting for a human choice; no content saved |
|
||||
| `rejected` | All alternatives declined; reformulation required |
|
||||
| `applying` | Choice recorded; file write or candidate recovery still required |
|
||||
| `pending_activation` | Content saved; index activation incomplete |
|
||||
| `active` | Saved correction matches the currently active revision |
|
||||
| `superseded` | The target was removed or changed after the saved correction |
|
||||
|
||||
The reviewer may retry a pending correction or continue the current question while
|
||||
leaving activation explicitly pending. The latter is not persistent-resolution success.
|
||||
`repair-show` refreshes target status; `repairs` lists the historical receipt status.
|
||||
The final Memory summary must not create a duplicate of a correction already saved here.
|
||||
|
||||
## Authorization and commands
|
||||
|
||||
Inspection/preparation requires an accessible open session in the same workspace.
|
||||
Applying either archive correction requires an administrator. Browser responses are
|
||||
also checked against the responding principal's `memory.manage` or `evidence.manage`
|
||||
permission and the Pi runtime owner. An administrator using another principal's runtime
|
||||
must resume it under their own account first, preserving truthful receipt attribution.
|
||||
Non-administrators may reject proposals or continue question review without changing
|
||||
the archives. The Pi shell guard blocks `repair-apply`; only the human gate invokes it.
|
||||
|
||||
The Python workflow CLI provides `memory repair-target`, `repair-prepare`, `repair-show`,
|
||||
`repair-apply`, and `repairs`. These are workflow integration commands, not new native
|
||||
installation commands. All accept `--session` and command-local `-c`; JSON output remains
|
||||
machine-readable. Proposal bodies are bounded to 1 MB. Durable receipts support both
|
||||
filesystem and server session storage without a persisted chat transcript.
|
||||
@@ -0,0 +1,248 @@
|
||||
# Editable Curated Evidence v4
|
||||
|
||||
Curated unit v4 makes the visible Markdown body authoritative. It uses the existing
|
||||
typed Evidence payloads and stable identifiers. Workspace descriptor v4 and Evidence
|
||||
descriptor v1/v2 are separate version numbers.
|
||||
|
||||
E1 implements the format, explicit conversion, local archive and consolidation API.
|
||||
E2 connects that API to the installed consolidation command, Evidence management
|
||||
page and runtime source selection. The local PSD preview now uses 35 converted units.
|
||||
|
||||
## Write or edit a file
|
||||
|
||||
Place units in `<workspace-root>/evidence/curated/<kind>/<name>.md`. Keep the existing
|
||||
`id` when editing. The directory must match `kind`. A new manual unit needs no external
|
||||
document, hash or encoded metadata:
|
||||
|
||||
```markdown
|
||||
---
|
||||
schema_version: 4
|
||||
id: evidence:order-key
|
||||
kind: domain
|
||||
language: en
|
||||
purposes: [sql_generation]
|
||||
applies_to:
|
||||
tables: [sales.orders]
|
||||
---
|
||||
|
||||
# Order key
|
||||
|
||||
## Rule
|
||||
|
||||
Join orders using the order number, financial year and company.
|
||||
```
|
||||
|
||||
Required metadata is `schema_version`, `id`, `kind`, `language`, and a nonempty
|
||||
`purposes` list. Purposes are `disambiguation`, `rewriting`, `schema_linking`, and
|
||||
`sql_generation`. Optional `applies_to` contains `concepts`, `tables`, and `columns`.
|
||||
Tables use `schema.table`; columns use `schema.table.column`.
|
||||
|
||||
The first H1 is the title. H2 headings identify the payload fields below. Heading
|
||||
spelling follows `language`: Italian for `it` and its regional variants, English
|
||||
otherwise. Keep structural headings when editing the text below them.
|
||||
|
||||
| Kind | English field headings | Italian field headings |
|
||||
| --- | --- | --- |
|
||||
| `domain` | Rule | Regola |
|
||||
| `glossary` | Definition, Synonyms, Variants | Definizione, Sinonimi, Varianti |
|
||||
| `enum` | Column, Values | Colonna, Valori |
|
||||
| `example` | Question, Interpretation | Domanda, Interpretazione |
|
||||
| `mapping` | Concept, Tables, Columns | Concetto, Tabelle, Colonne |
|
||||
| `normalization` | Input, Output, Rule | Input, Output, Regola |
|
||||
| `formula` | Concept, Columns, SQL | Concetto, Colonne, SQL |
|
||||
| `reference` | URL, Label, Description | URL, Etichetta, Descrizione |
|
||||
|
||||
List fields use one `- value` per line. Empty optional lists may be omitted. Quoted
|
||||
JSON strings within bullets preserve unusual or multiline values during conversion.
|
||||
Enum values use `### "stored value"`, followed by their meaning; `### ""` represents
|
||||
an empty stored value. Formula SQL uses a fenced `sql` block containing one PostgreSQL
|
||||
expression. Whole queries and mutation statements remain invalid.
|
||||
|
||||
Nested prose headings and fenced examples are supported inside text fields. An H2
|
||||
matching a field heading is structural outside a code fence. Duplicate fields, missing
|
||||
required fields, duplicate metadata keys and malformed payloads are rejected. There
|
||||
is no second title or payload in frontmatter and no hidden authoritative rule text.
|
||||
Conversion fails explicitly if a legacy payload cannot be represented losslessly.
|
||||
|
||||
## Current provenance and original source
|
||||
|
||||
The host supplies document provenance when refining source material: relative source
|
||||
path, normalized source hash and exact supporting excerpts. A manual unit can omit
|
||||
`provenance`. Consolidation records `kind: manual` and the supplied curator identity.
|
||||
|
||||
A visible change to a previously recorded unit becomes a manual declaration. If that
|
||||
unit originated from a document, its former document provenance is retained under
|
||||
`original`. The original excerpts establish lineage; they do not assert that the
|
||||
source contains the new wording. Retrieval carries this distinction through typed
|
||||
metadata. Curators edit content; the service updates managed provenance.
|
||||
|
||||
Unchanged document declarations still require matching source bytes and excerpts.
|
||||
Replacing a source requires an explicit refresh through the E3 source-review path. Ordinary preparation
|
||||
is blocked on an initialized local archive, preventing regenerated source material
|
||||
from overwriting corrections or restoring deletions. Legacy `resolve` is likewise
|
||||
blocked there; local file corrections and the archive API own those changes.
|
||||
|
||||
## Persistent archive and activation
|
||||
|
||||
```text
|
||||
<workspace-root>/
|
||||
.evidence-archive.lock
|
||||
evidence/
|
||||
source/ # acquired original documents
|
||||
curated/<kind>/*.md # editable primary content
|
||||
local-manifest.yaml # derived declarations and deletion records
|
||||
.local/
|
||||
state.yaml # baseline, pending and active revisions
|
||||
snapshots/<revision>/ # immutable units, source bytes and manifest
|
||||
```
|
||||
|
||||
Keep the complete Evidence tree and its managed metadata in backups and the operator's
|
||||
Git review. Historical source bytes and deletion records are needed to preserve manual
|
||||
care across subsequent imports. The separate corpus cache and Qdrant index are derived.
|
||||
The lock file only coordinates local service operations.
|
||||
|
||||
`LocalEvidenceArchive.initialize()` records the pre-edit baseline without activation.
|
||||
`consolidate(actor=..., activate=...)` validates files, derives provenance, records
|
||||
deletions and source suppression, and creates an immutable candidate. The activation
|
||||
callback receives that snapshot and must raise if indexing is blocked or fails. Only
|
||||
successful activation advances `active_snapshot()`. Without a callback the result is
|
||||
explicitly `pending_activation`; saving a file alone never changes this pointer.
|
||||
|
||||
The same candidate can be retried after an index failure. Interrupted managed writes
|
||||
are replayed only when the operator's file bytes have not changed. A missing curated
|
||||
directory is an availability error, not proof that all units were deleted. Removing
|
||||
unit files from an accessible directory records deletion without deleting their sources.
|
||||
The API also provides `get`, revision-checked `save`, and revision-checked `remove` for
|
||||
future deliberate workflow corrections. Concurrent external edits produce conflicts.
|
||||
|
||||
These boundaries are exercised with the existing corpus pipeline and real Qdrant.
|
||||
An initialized installation reads only its active local snapshot, including during
|
||||
ordinary preprocessing. Unconsolidated edits are visible in Administration but do
|
||||
not enter retrieval. Before initialization, the pinned repository source still works.
|
||||
|
||||
## Administration and installed command
|
||||
|
||||
Open **Administration → Evidence management**. This independent page requires the
|
||||
`evidence.manage` permission and no active session. It shows complete units, source
|
||||
lineage, review items, file errors, filters, and changes relative to the active snapshot.
|
||||
Edit the displayed Markdown path using an external editor. Refresh files to inspect
|
||||
the result, then run the command shown by the page:
|
||||
|
||||
```sh
|
||||
tht --installation /absolute/path/thothii-installation.yaml \
|
||||
workspace evidence consolidate --workspace psd-clinical
|
||||
```
|
||||
|
||||
The installed command accepts `--json`. It validates and activates Evidence using
|
||||
the existing corpus pipeline and embedding service. It does not scan the DWH, run
|
||||
full workspace preprocessing, change Catalog/Schema readiness, or execute Git.
|
||||
If indexing fails after saving, the archive retains the candidate for retry and the
|
||||
previous active revision remains selected. Validation errors identify corrections
|
||||
to make in the files. Structural and review checks still apply; initialized archives
|
||||
do not require the legacy repository's fixed retrieval-evaluation fixture, whose
|
||||
expected IDs would otherwise prevent deliberate local deletions.
|
||||
|
||||
The canonical workspace root is `<workspace-registry-root>/repo/<workspace-id>`.
|
||||
Snapshots and the derived corpus are separate. For a registry in a Docker volume,
|
||||
copy its existing `repo` to a persistent host directory before enabling
|
||||
`deploy/compose.evidence-host.yaml`; set `THT_EVIDENCE_HOST_REGISTRY_ROOT` to that
|
||||
directory and include the override in the installation descriptor. Core and
|
||||
workspace-maintenance must mount the same checkout. Keep registry state/snapshots
|
||||
on their existing volume. The page only presents a host path when configured; it
|
||||
does not label an internal container path as a usable editor path.
|
||||
|
||||
After successful consolidation, inspect and commit the complete workspace Evidence
|
||||
tree, including managed manifests, snapshots, and deletion records, then push manually.
|
||||
The page provides quoted POSIX-shell examples for status, diff, add, commit, and push.
|
||||
Do not commit only the edited Markdown. Ordinary Git operations remain the operator's
|
||||
responsibility. E3 source decisions use this same activation boundary.
|
||||
|
||||
**Clear** removes derived Reference/corpus data while retaining editable files,
|
||||
snapshots and Memory. It still requires full workspace preprocessing to recreate
|
||||
Reference/Schema readiness; Evidence consolidation does not satisfy that gate.
|
||||
|
||||
## Import drafts and refresh sources
|
||||
|
||||
Place externally authored Markdown drafts in `<workspace-root>/evidence/incoming/`.
|
||||
The specialist needs no installation account or database access to write a draft.
|
||||
Copying the draft to the installation and choosing **Import or refresh sources** in
|
||||
Evidence management explicitly starts acquisition and refinement. The equivalent
|
||||
installed command is:
|
||||
|
||||
```sh
|
||||
tht --installation /absolute/path/thothii-installation.yaml \
|
||||
workspace evidence refresh --workspace psd-clinical
|
||||
```
|
||||
|
||||
This reads local `incoming/**/*.md` and original `source/**/*.md` files, excluding
|
||||
managed `source/acquired/` versions. It also reads configured HTTP and S3 sources
|
||||
through the existing read-only adapters and network policies. After local archive
|
||||
initialization, filesystem descriptors use this local authoring tree; ordinary
|
||||
runtime/preprocessing never fetches remote source changes. No source-server write
|
||||
credential is needed. The existing Pi authoring refiner runs once for each changed
|
||||
document, without session state or tools. Unchanged source hashes skip refinement.
|
||||
|
||||
All acquisitions and proposals must succeed before the new comparison set is
|
||||
recorded. An access or refinement failure preserves previous comparisons and active
|
||||
Evidence. A source absent from a successful discovery is marked missing and never
|
||||
treated as permission to delete units. Restore an accidentally missing local original
|
||||
file before consolidating its document-derived units, or explicitly retire those units.
|
||||
|
||||
Each changed source has a durable comparison showing current local units, complete
|
||||
proposed content, supporting excerpts, and IDs that replacement would retire:
|
||||
|
||||
- **Keep local Evidence** retains the current wording as a manual declaration, with
|
||||
its original documentary lineage preserved. The changed source is acknowledged;
|
||||
the next unchanged refresh does not reopen that decision.
|
||||
- **Use proposed Evidence** adopts the displayed proposal and explicitly retires the
|
||||
displayed omitted IDs. The source version and provenance change together.
|
||||
|
||||
Both choices save and activate through the same local consolidation/index pipeline.
|
||||
Review items block adoption; correct the original draft and refresh, or keep local
|
||||
content. There is no automatic merge based on a model's semantic conflict assessment.
|
||||
Any change to an affected curated file invalidates the comparison and requires a new
|
||||
refresh. If indexing fails after the decision is saved, use **Retry saved decision**;
|
||||
this reuses acquired content without fetching sources again. An intervening external
|
||||
edit is never silently overwritten by recovery.
|
||||
|
||||
Headless operators can make the same decision using the source ID and comparison
|
||||
revision from the local source registry or administration response:
|
||||
|
||||
```sh
|
||||
tht --installation /absolute/path/thothii-installation.yaml \
|
||||
workspace evidence decide --workspace psd-clinical \
|
||||
--source-id <64-hex-source-id> --revision <64-hex-comparison-revision> \
|
||||
--decision keep
|
||||
```
|
||||
|
||||
Use `--decision replace` to adopt the proposal. All installed commands accept `--json`.
|
||||
The Python `evidence sources` worker is internal to this installed command/API surface.
|
||||
|
||||
`evidence/.local/sources.json` stores source identities, comparisons and retry journals.
|
||||
`evidence/.local/acquisitions/` preserves original acquired bytes and credential-free
|
||||
remote provenance. Adopted normalized documents live under
|
||||
`evidence/source/acquired/<source-id>/<content-hash>.md`. Versioned paths let a new
|
||||
document and an older manual declaration's original source coexist. Include all of
|
||||
these files in the existing manual Git/backup sequence. Do not edit managed acquired
|
||||
versions: edit the original local draft or refresh its remote origin.
|
||||
|
||||
Deleted IDs remain reserved. Once a source has had a curated deletion, fresh model
|
||||
IDs from that source are conservatively suppressed as well: changing an ID must not
|
||||
restore retired knowledge. Existing surviving IDs can still receive reviewed updates;
|
||||
deliberate new knowledge can be written as a manual Evidence file. Refresh is bounded
|
||||
to 200 documents and 100 MiB per operation, in addition to each adapter's limits.
|
||||
|
||||
## Convert an existing workspace
|
||||
|
||||
The existing workflow CLI command `tht evidence migrate <workspace-root>` converts
|
||||
unit versions 1–3 to 4 deterministically and initializes the archive baseline. It
|
||||
preserves IDs, typed content, provenance and review items, with no model call or Git
|
||||
commit. It does not activate a local index. Review items still block consolidation.
|
||||
The command's existing Git-worktree path check remains in effect.
|
||||
|
||||
The first installed consolidation performs this conversion automatically when the
|
||||
legacy manifest is present, then validates and activates the result. Preserve the
|
||||
existing checkout in backups before upgrading. The E1 validation used an isolated
|
||||
copy; E2 also converted and indexed all 35 units on the running local preview.
|
||||
See the [E1 validation report](../plans/2026-09-09-evidence-e1-validation.md) and
|
||||
[E2 validation report](../plans/2026-09-09-evidence-e2-validation.md).
|
||||
@@ -6,8 +6,9 @@ When present, `evidence` is strict: it contains `source` and a defaulted strict
|
||||
source variant and the policy reject unknown keys.
|
||||
|
||||
The version numbers are intentionally separate: the Evidence descriptor supports v1/v2, while the
|
||||
latest Curated Evidence Unit format is v3. There is no Evidence descriptor v3/v4 and no Curated
|
||||
Evidence Unit v4.
|
||||
latest Curated Evidence Unit format is [v4](curated-evidence-v4.md). There is no Evidence
|
||||
descriptor v3/v4. The editable local archive is implemented in E1; installation integration
|
||||
is the next increment, E2.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
@@ -67,9 +68,11 @@ ignore it. Domain rules also retain their exact canonical text in an invisible `
|
||||
comment while presenting long prose as paragraphs, labelled subsections, and semicolon-derived
|
||||
lists. Runtime chunking reads the parsed canonical rule, not this review-only presentation.
|
||||
|
||||
Newly prepared units use v3. `tht evidence migrate <workspace-root>` upgrades v1 and v2 units and
|
||||
canonicalizes an older v3 presentation locally without a model call, commit, publication, or
|
||||
semantic change.
|
||||
The representations above are legacy conversion inputs. Newly prepared units use editable v4:
|
||||
short YAML metadata, a visible H1 title and typed H2 payload fields, with no hidden content copy.
|
||||
`tht evidence migrate <workspace-root>` converts v1–v3 to v4 and initializes a local archive
|
||||
baseline without a model call, commit, activation, or semantic change. See the
|
||||
[v4 editing and consolidation contract](curated-evidence-v4.md).
|
||||
|
||||
### Example: filesystem
|
||||
|
||||
|
||||
@@ -14,12 +14,30 @@ tht --installation <absolute>/thothii-installation.yaml workspace preprocess run
|
||||
|
||||
tht --installation <absolute>/thothii-installation.yaml workspace preprocess clear
|
||||
--workspace <id> [--json]
|
||||
|
||||
tht --installation <absolute>/thothii-installation.yaml workspace evidence consolidate
|
||||
--workspace <id> [--json]
|
||||
|
||||
tht --installation <absolute>/thothii-installation.yaml workspace evidence refresh
|
||||
--workspace <id> [--json]
|
||||
|
||||
tht --installation <absolute>/thothii-installation.yaml workspace evidence decide
|
||||
--workspace <id> --source-id <64-hex> --revision <64-hex>
|
||||
--decision keep|replace [--json]
|
||||
```
|
||||
|
||||
There are no public partial commands for DWH introspection, LSH, FK suggestions, schema indexing,
|
||||
Evidence indexing, or Qdrant rebuild. `preprocess run` does not accept `--resume`, `--dry-run`, a
|
||||
or Qdrant rebuild. The separate Evidence curation command validates editable local files and
|
||||
activates only their index; it does not satisfy workspace preprocessing readiness or execute Git.
|
||||
See [Curated Evidence v4](curated-evidence-v4.md#administration-and-installed-command).
|
||||
Source refresh acquires and refines only on explicit request, saving comparisons without
|
||||
changing active Evidence. Source decisions activate through the same Evidence-only
|
||||
pipeline and preserve Catalog readiness. Their envelopes reject arbitrary URLs, paths
|
||||
and extra flags; source locations and credentials come from installation configuration.
|
||||
`preprocess run` does not accept `--resume`, `--dry-run`, a
|
||||
generation identifier, or a rollback option. Re-running it replaces the preceding derived output.
|
||||
`preprocess clear` removes all replaceable preprocessing output and preserves runtime memory.
|
||||
`preprocess clear` removes all replaceable preprocessing output and preserves runtime memory
|
||||
and the canonical local Evidence archive. Full preprocessing remains required afterward.
|
||||
|
||||
## Sources of truth
|
||||
|
||||
@@ -29,8 +47,10 @@ generation identifier, or a rollback option. Re-running it replaces the precedin
|
||||
- PostgreSQL Metadata Catalog is the sole database authority. It owns the workspace/database
|
||||
association, installation-local binding, tables, columns, descriptions, sensitivity flags,
|
||||
physical foreign keys, and active logical relationships.
|
||||
- The workspace Git revision remains authoritative for Evidence. Evidence Descriptor v1/v2 and
|
||||
Curated Evidence Unit v3 are unchanged; there is no Evidence v4.
|
||||
- Evidence Descriptor v1/v2 still configures the initial source. Initialized archives use
|
||||
editable Curated Evidence Unit v4 and the last successfully activated local snapshot.
|
||||
Ordinary preprocessing never imports unconsolidated working-tree edits. Before initialization,
|
||||
the pinned workspace Git source remains supported.
|
||||
|
||||
No metadata is imported from legacy workspace YAML or `physical.yaml`/`annotations.yaml`.
|
||||
|
||||
@@ -98,9 +118,8 @@ generation produced for another database or revision.
|
||||
|
||||
`workspace preprocess clear` is intentionally narrower than deleting all semantic data. It:
|
||||
|
||||
1. copies any `memory` and `solved_question` records still present in the pre-split workspace
|
||||
collection to `<workspace>-memory`, then retires that legacy collection (a normal preprocessing
|
||||
write performs the same one-time cutover if clear was not invoked first);
|
||||
1. leaves `<workspace>-memory` unchanged; Memory projections are reconstructed only from
|
||||
the authoritative PostgreSQL archive, never imported from legacy vector payloads;
|
||||
2. deletes `<workspace>-reference`;
|
||||
3. removes the active LSH generation, Evidence corpus, private Catalog snapshot, and derived job
|
||||
checkpoints;
|
||||
|
||||
+52
-3
@@ -2,7 +2,30 @@
|
||||
|
||||
This page describes the complete workspace Evidence lifecycle: where original material lives, how curated units are produced, when they become available at runtime, and what the author and reviewer are responsible for.
|
||||
|
||||
## Publication rule
|
||||
## Editable local Evidence
|
||||
|
||||
E1 adds [Curated Evidence v4 and a persistent local archive](contracts/curated-evidence-v4.md).
|
||||
The visible title and payload fields are authoritative Markdown. New manual units need no
|
||||
external source; consolidation records their curator and distinguishes later corrections
|
||||
from original documentary provenance. The core archive API creates immutable candidates
|
||||
and advances its active pointer only after successful indexing.
|
||||
|
||||
E2 adds **Administration → Evidence management**, actual host file paths, complete
|
||||
browsing and filtering, and the installed `tht workspace evidence consolidate
|
||||
--workspace <id>` command. Edit files externally, consolidate to activate them, then
|
||||
review and run Git manually. Runtime consumes only the active local snapshot.
|
||||
The [v4 contract](contracts/curated-evidence-v4.md#administration-and-installed-command)
|
||||
describes host mounting, first conversion, failure recovery and Clear behavior.
|
||||
The local PSD preview has 35 converted and indexed units. E3 adds explicit import/refresh
|
||||
from local drafts and configured HTTP/S3 sources, durable current/proposed comparisons,
|
||||
and keep/replace decisions with activation and retry. See
|
||||
[Import drafts and refresh sources](contracts/curated-evidence-v4.md#import-drafts-and-refresh-sources).
|
||||
Workflow gate corrections remain the subsequent shared increment, X1.
|
||||
|
||||
## Existing repository publication path
|
||||
|
||||
The remainder describes the legacy, uninitialized repository source path. Initialized
|
||||
v4 local archives use the lifecycle above; manual declarations need no source document.
|
||||
|
||||
The workspace repository is the versioned source. ThothII reads it, validates it, and publishes an atomic generation. It does not modify, commit, or push the author's repository.
|
||||
|
||||
@@ -46,7 +69,33 @@ The legacy configuration may expose `source_root`, such as `${THT_DOCS_ROOT}` or
|
||||
|
||||
HTTP and S3 are separate adapters. They do not use the filesystem structure `source/` and `curated/`, but they must still provide stable provenance, without credentials in URIs, under the adapter-specific contract.
|
||||
|
||||
## What a curated unit must contain
|
||||
## What an editable curated unit contains
|
||||
|
||||
New preparation produces unit schema v4. The first H1 contains its title; documented H2
|
||||
sections contain the typed payload. A minimal manual unit is:
|
||||
|
||||
```markdown
|
||||
---
|
||||
schema_version: 4
|
||||
id: evidence:order-key
|
||||
kind: domain
|
||||
language: en
|
||||
purposes: [sql_generation]
|
||||
---
|
||||
|
||||
# Order key
|
||||
|
||||
## Rule
|
||||
|
||||
Join orders using the order number, financial year and company.
|
||||
```
|
||||
|
||||
Use `tht evidence migrate <workspace-root>` for deterministic legacy conversion. The
|
||||
conversion preserves typed content and initializes an archive baseline; it does not
|
||||
activate the local corpus. See the [v4 contract](contracts/curated-evidence-v4.md) for
|
||||
all eight kinds, provenance, file layout and the E1/E2 boundary.
|
||||
|
||||
## Legacy v3 representation
|
||||
|
||||
Canonical Curated Evidence v3 hides canonical machine metadata in an HTML comment and renders the
|
||||
whole review surface as real Markdown. GitHub therefore shows no frontmatter table. The body layout
|
||||
@@ -94,7 +143,7 @@ La fascia pediatrica comprende i pazienti con età inferiore a 18 anni.
|
||||
The actual files contain invisible `tht:` comments for canonical metadata and typed-field
|
||||
boundaries. Removing, duplicating, or desynchronizing them makes validation fail closed instead of
|
||||
silently ignoring content. Unit schemas v1 and v2 remain readable for compatibility, but newly
|
||||
prepared units use v3.
|
||||
prepared units use v4. Unit v3 remains readable as a conversion input.
|
||||
|
||||
Curated units must be atomic, readable by a second reviewer, and supported by the source.
|
||||
Provenance references must lead back to the original file and the passage that supports the claim.
|
||||
|
||||
+208
-222
@@ -1,244 +1,230 @@
|
||||
# Memory management
|
||||
|
||||
This document describes how Memory currently works in ThothII: its conceptual model, lifecycle, persistence, semantic search, review gates, session display, and main technical limits.
|
||||
Memory holds reusable knowledge for a workspace. PostgreSQL is the authoritative
|
||||
archive; Qdrant contains a rebuildable search projection. The harness owns both
|
||||
the administrative operations and the verification of retrieved results.
|
||||
|
||||
## Architectural summary
|
||||
## Administration
|
||||
|
||||
A Memory item is domain knowledge that can be reused across questions. It is not a copy of one question's schema linking.
|
||||
Open **Administration → Memory management**, immediately after Database management.
|
||||
An administrator selects the workspace explicitly. No active session, DWH binding,
|
||||
embedding service or Qdrant connection is required to browse and edit the archive.
|
||||
PostgreSQL must be available.
|
||||
|
||||
The page provides a paginated list, text/ID search, stable sorting, and combined
|
||||
filters for family, concepts, database, table, column, origin and update date.
|
||||
Filtering happens across the entire archive before pagination. Each card has a
|
||||
complete detail view, an editable form, cancellation of unsaved changes, and an
|
||||
explicit deletion confirmation.
|
||||
|
||||
| Family | Content |
|
||||
| --- | --- |
|
||||
| Domain clarification | A reusable definition or interpretation, with scope and context. |
|
||||
| SQL rule | Guidance for constructing SQL, with scope and rationale. |
|
||||
| Solved question | A question, its approved SQL and context; used as a consultative exemplar. |
|
||||
| Explained error | A correction and its rationale, to avoid repeating a known error. |
|
||||
|
||||
All cards have a stable `mem-<UUID>` identity, title, scope, origin and timestamps.
|
||||
Manual cards have no invented source session or decision. Workflow cards retain
|
||||
their source references when an administrator edits them. There is no editorial
|
||||
revision history.
|
||||
|
||||
The form also manages concepts, structured database/schema/table/column
|
||||
dependencies, and links to other cards with an explicit meaning. Links can only
|
||||
connect cards in the same workspace. Card, dependency and outgoing-link changes
|
||||
are committed together. Deleting a card removes its incident links and dependencies,
|
||||
while keeping the other cards, Evidence and Catalog metadata.
|
||||
|
||||
## Save, failure and recovery
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
CLARIFY["F1 concept clarified"] --> REVIEW["F8 reviewer review"]
|
||||
REVIEW -->|"accepted"| REGISTRY["registry.jsonl"]
|
||||
REVIEW -->|"declined"| LOCAL["Session decision only"]
|
||||
REGISTRY --> VECTOR["Qdrant semantic index"]
|
||||
VECTOR --> FUTURE["Future F2 retrieval"]
|
||||
FUTURE --> PROPOSAL["Reviewer proposal"]
|
||||
flowchart LR
|
||||
EDIT["Admin or workflow"] --> SQL["PostgreSQL transaction"]
|
||||
SQL --> CARD["Current card and links"]
|
||||
SQL --> WORK["Pending projection"]
|
||||
WORK --> Q["Qdrant"]
|
||||
Q --> CHECK["Verify current card and projection"]
|
||||
CARD --> CHECK
|
||||
CHECK --> REVIEW["Recall for human review"]
|
||||
```
|
||||
|
||||
```text
|
||||
F1: clarify a concept
|
||||
│
|
||||
▼
|
||||
concept_clarified decision in the session ledger
|
||||
│
|
||||
▼
|
||||
F8: reviewer decides whether to promote it
|
||||
│
|
||||
├── global registry registry.jsonl
|
||||
└── Qdrant semantic index
|
||||
│
|
||||
▼
|
||||
F2 in a future session
|
||||
search and proposal to the reviewer
|
||||
```
|
||||
The service serializes each workspace's mutations. It first commits content and
|
||||
the projection operation in PostgreSQL, then propagates to Qdrant. A failed save
|
||||
is different from **saved, index update incomplete**. In the latter case the
|
||||
current content is already available in administration, while its previous vector
|
||||
result is excluded from recall.
|
||||
|
||||
The main invariant is `REUSABLE_TYPES = {"concept_clarified"}`: only clarified concepts can be generated, saved, searched, or proposed as Memory. Decisions such as `table_promoted`, `table_excluded`, and `column_promoted` remain local to the question.
|
||||
The **Pending index updates** section offers an explicit retry, including cleanup
|
||||
for deleted cards. These operations survive a restart. Retry reads the current
|
||||
archive state and cannot restore an earlier edit or a deleted card. Technical
|
||||
revisions are internal consistency markers, not user-managed card statuses.
|
||||
|
||||
## The three management levels
|
||||
Every recall hit must resolve to a current card in the requested workspace, with
|
||||
a matching valid projection. The response is reconstructed from PostgreSQL, never
|
||||
from an unverified Qdrant payload. Deleted, orphaned and stale points are excluded
|
||||
for both domain Memory and solved-question exemplars. An unavailable archive is
|
||||
an operational error, not a successful empty archive.
|
||||
|
||||
| Level | Content | Function |
|
||||
Rebuilding Memory uses only authoritative cards. It does not import JSONL files,
|
||||
historical session artifacts or old vector payloads. Reference preprocessing keeps
|
||||
the Memory collection separate and does not migrate legacy Memory payloads.
|
||||
|
||||
## Hybrid recall and links
|
||||
|
||||
Memory uses dense embeddings and Qdrant BM25, fused with reciprocal rank fusion.
|
||||
Both branches receive the same workspace, family and scope filters before candidate
|
||||
selection. Indexed text includes content, scope, rationale, question, exemplar SQL,
|
||||
concepts and qualified physical dependencies. Both indexing and querying use the
|
||||
workspace language (`en` or `it`), including manual administration without a DWH binding.
|
||||
|
||||
The workflow CLI binds recall to its configured database and schema. Optional
|
||||
`--filters` JSON can narrow the business `scope`, `concepts`, `table` and `column`.
|
||||
Business scope is an exact string; every requested concept must be present. Physical
|
||||
context matches a single structured dependency: database, schema, table and column
|
||||
cannot be satisfied by unrelated entries. A card without dependencies is workspace-wide;
|
||||
a database-only or table-only dependency also applies to descendants. Without a table
|
||||
filter, table-specific knowledge in the selected database/schema remains discoverable.
|
||||
Filters cannot override the configured database/schema. Free-text business scope is
|
||||
not automatically interpreted or inferred from the question.
|
||||
|
||||
The core expands outgoing links from current, eligible search candidates. It applies
|
||||
the same filters and workflow-family restrictions to destinations and intermediate
|
||||
cards. Removed, pending, previously decided and out-of-scope cards cannot act as bridges.
|
||||
Traversal allows two hops, at most 20 outgoing links per card (stable target-ID order),
|
||||
200 distinct card lookups and 400 inspected links in total. Search requests
|
||||
`min(100, max(20, 3 × top))` seeds; the result limit remains between 1 and 100.
|
||||
|
||||
All candidates are ranked together using `1 / (60 + seed rank)` for direct hits,
|
||||
plus the strongest linked contribution, decayed by `0.5` per hop. Repeated paths
|
||||
do not accumulate votes. Ties use card ID. The returned `score` is a ranking score,
|
||||
not cosine similarity or a confidence estimate. `retrieval.path` shows the strongest
|
||||
link path, or just the card ID for an exclusively direct result. PostgreSQL content,
|
||||
links and eligibility are resolved under the workspace operation lock after search.
|
||||
|
||||
Migration `002_hybrid_projection.sql` marks the format of old dense projections as
|
||||
incompatible without changing their authoritative cards. They appear in pending
|
||||
updates and are excluded from recall until explicit retry or `memory index` succeeds.
|
||||
Memory writes can add a missing BM25 sparse vector to their collection; an incompatible
|
||||
existing vector configuration fails visibly and leaves recovery pending. Reading never
|
||||
silently falls back to dense retrieval. Reference remains independently managed.
|
||||
An explicit `memory index` can also recreate a missing Memory collection before
|
||||
rebuilding its projections; it never imports records from another source.
|
||||
|
||||
## Workflow integration
|
||||
|
||||
During the workflow, Pi prepares reusable proposals in the session artifact
|
||||
`memory_proposals.json`. Each proposal names effective approved source decisions,
|
||||
the content and scope, its rationale, and any physical dependencies or links.
|
||||
Unexplained failures, rejected options and simple table selections do not create
|
||||
reusable knowledge. Exact existing cards are reused; semantic similarity alone
|
||||
never authorizes replacement. Updates name the existing card and its current revision.
|
||||
|
||||
At F8, `reviewer_memory_promote` presents one editable Memory summary, including
|
||||
the approved solved question. The reviewer chooses additions and updates, edits
|
||||
their content, scope, dependencies and links, or declines everything. Approved SQL
|
||||
is read only here: changing the solution requires returning to SQL review.
|
||||
Only selected cards and their links are committed. Invalid links or stale updates
|
||||
roll back the entire selection. Links between selected new cards are resolved
|
||||
inside the same transaction. An explicit update preserves the existing identity
|
||||
and origin, including manually authored content.
|
||||
|
||||
A durable review receipt makes repeated delivery idempotent and recovers the
|
||||
gap between saving Memory and recording `memory_summary_reviewed` in the session
|
||||
ledger. Retry never recreates a deleted card. The gate then closes F8 and finalizes;
|
||||
finalization itself performs no automatic Memory writes. Pending indexing remains
|
||||
visible and recoverable in administration.
|
||||
|
||||
F2 consumes domain clarifications and excludes already decided Memory. In F4,
|
||||
F6 and F7, `memory rules` retrieves applicable SQL rules and explained errors.
|
||||
Pi presents their use in the existing schema, CTE or SQL approval gate.
|
||||
Exemplar search remains consultative. Retrieval never constitutes approval.
|
||||
Persistent Memory/Evidence conflict repair remains part of the joint X1 increment.
|
||||
|
||||
## Physical schema changes
|
||||
|
||||
After a successful physical Catalog synchronization, the backend passes the exact
|
||||
removed tables and columns, database, schema and run identity to Memory. Only cards
|
||||
with matching structured dependencies are deleted, together with their incident
|
||||
links and searchable projections. Global cards and objects outside the synchronized
|
||||
scope survive. Manual Catalog cleanup and failed DWH scans never trigger this deletion.
|
||||
|
||||
The Catalog transaction records a pending `memory_cleanup` phase before committing
|
||||
the physical change. If cleanup or indexing fails, the run retains the original
|
||||
removals. Retry completes that same operation without rescanning the DWH or relying
|
||||
on a new diff. A new synchronization is blocked until this cleanup is completed.
|
||||
The Memory deletion receipt and vector tombstones make the operation repeatable
|
||||
across restarts. The synchronization drawer reports deleted Memory cards and errors.
|
||||
|
||||
## API and commands
|
||||
|
||||
The administrative HTTP surface requires `memory.manage`, included in the existing
|
||||
admin role. The backend checks workspace identity and passes its trusted principal
|
||||
and a protected request snapshot to the harness. The harness independently checks
|
||||
the principal; ordinary users cannot bypass administration through the CLI.
|
||||
Production authentication and CSRF protections apply to the new routes.
|
||||
|
||||
| Method | Path below `/api/workspaces/:workspaceId/memory` | Operation |
|
||||
| --- | --- | --- |
|
||||
| Session ledger | `concept_clarified`, `memory_promoted`, `memory_promotion_declined` | Audit and state for one session |
|
||||
| Global registry | `mem-XXXX` records in `registry.jsonl` | Current canonical Memory archive |
|
||||
| Qdrant index | Embeddings and metadata derived from the registry | Semantic search |
|
||||
| GET | root | Search, filter and paginate the archive |
|
||||
| POST | root | Create a card |
|
||||
| GET | `/:cardId` | Read a complete card |
|
||||
| PUT | `/:cardId` | Save content, links and dependencies together |
|
||||
| DELETE | `/:cardId` | Delete a card and incident links |
|
||||
| GET | `/pending` | List incomplete projection operations |
|
||||
| POST | `/:cardId/retry` | Retry current projection work, including deletion |
|
||||
|
||||
The ledger contains provenance and human decisions. The global record contains reusable text. The vector index is a search projection, not the place where the workflow records decisions directly.
|
||||
|
||||
## What can become Memory
|
||||
|
||||
During F1, the workflow records clarifications as `concept_clarified` decisions. A clarification can express:
|
||||
|
||||
- definitions of production or organizational concepts;
|
||||
- inclusion and exclusion criteria for a product line;
|
||||
- formulas and calculation methods;
|
||||
- interpretations of time periods;
|
||||
- mappings to specific tables and columns;
|
||||
- the meaning of flags, codes, or indicators.
|
||||
|
||||
The `MemoryRecord` model contains:
|
||||
|
||||
- `id`, such as `mem-0001`;
|
||||
- the timestamp, session, and sequence of the original decision;
|
||||
- `type`;
|
||||
- `subject`;
|
||||
- `detail`;
|
||||
- `rationale`;
|
||||
- `question_context`;
|
||||
- `tables` e `concepts`.
|
||||
|
||||
For new Memory items, the type is always `concept_clarified` and `tables` starts empty. A table or column may appear in the explanation as a technical mapping, but it cannot be the Memory item's standalone concept.
|
||||
|
||||
Valid example:
|
||||
|
||||
> Ablation means a procedure with `ablazione_transcatetere = TRUE`, counted with `COUNT(DISTINCT cod_paz)` by year.
|
||||
|
||||
Invalid examples:
|
||||
|
||||
- `fact_cardioversione` as approved Memory;
|
||||
- `dim_time` as rejected Memory;
|
||||
- an "include this table" decision saved for future questions.
|
||||
|
||||
The workflow skill also documents this rule in [harness/.pi/skills/tht-sessione/SKILL.md](https://git.tylconsulting.it/mptyl/ThothII/src/branch/main/harness/.pi/skills/tht-sessione/SKILL.md#L217).
|
||||
|
||||
## Promotion at the end of the session: F8
|
||||
|
||||
At the end of the workflow, the `reviewer_memory_promote` gate runs a deterministic preview:
|
||||
CLI configuration remains a per-command option. Commands emit pure JSON:
|
||||
|
||||
```text
|
||||
tht memory promote --session <id> --preview --json
|
||||
tht memory list --filters '{"family":"sql_rule","page":1}' -c <runtime.yaml>
|
||||
tht memory show <card-id> -c <runtime.yaml>
|
||||
tht memory create --data <card.json> -c <runtime.yaml>
|
||||
tht memory update <card-id> --data <card.json> -c <runtime.yaml>
|
||||
tht memory delete <card-id> --yes -c <runtime.yaml>
|
||||
tht memory pending -c <runtime.yaml>
|
||||
tht memory retry <card-id> -c <runtime.yaml>
|
||||
tht memory index -c <runtime.yaml>
|
||||
tht memory search "<question>" --session <id> --json -c <runtime.yaml>
|
||||
tht memory search "<question>" --filters '{"table":"orders","column":"id","scope":"Sales"}' --json -c <runtime.yaml>
|
||||
tht memory solved-search "<question>" --json -c <runtime.yaml>
|
||||
tht memory rules "<question>" --session <id> --json -c <runtime.yaml>
|
||||
tht memory propose --session <id> --data <proposals.json> -c <runtime.yaml>
|
||||
tht memory summary --session <id> --json -c <runtime.yaml>
|
||||
tht memory solved-index <session-id> --json -c <runtime.yaml>
|
||||
```
|
||||
|
||||
The preview:
|
||||
`memory index` rebuilds both domain and solved-question projections.
|
||||
`solved-index` only retries an existing authoritative source receipt.
|
||||
The reviewer gate owns `memory review-apply`; Pi must not call it directly.
|
||||
Migration `003_review_receipts.sql` adds durable review and physical-cleanup receipts.
|
||||
The backend uses `memory admin --workspace <id> -c <protected-request.json>` so
|
||||
administration does not materialize session or DWH configuration.
|
||||
|
||||
1. reads the session's effective decisions;
|
||||
2. considers only `concept_clarified`;
|
||||
3. discards decisions already promoted;
|
||||
4. discards sequences already declined in F8;
|
||||
5. deduplicates equivalent content;
|
||||
6. proposes at most five candidates.
|
||||
## Installation and storage
|
||||
|
||||
The code applies filtering and deduplication in
|
||||
[harness/tht/memory/core.py](https://git.tylconsulting.it/mptyl/ThothII/src/branch/main/harness/tht/memory/core.py); the gate applies an additional defensive filter in
|
||||
[harness/.pi/extensions/gate/memory/index.js](https://git.tylconsulting.it/mptyl/ThothII/src/branch/main/harness/.pi/extensions/gate/memory/index.js).
|
||||
Memory shares the installation's existing PostgreSQL service, using its own
|
||||
`thoth_memory` schema and versioned harness migration pack. The existing
|
||||
`catalog-migrate` preparation service runs Catalog migrations followed by
|
||||
`python -m tht.memory.migrate`. The core image includes both migration runners.
|
||||
Ordinary API requests never migrate the schema.
|
||||
|
||||
The reviewer sees one preselected checklist. For each candidate:
|
||||
Connection credentials come from the existing generated `THT_CATALOG_DB_HOST`,
|
||||
`THT_CATALOG_DB_PORT`, `THT_CATALOG_DB_NAME`, `THT_CATALOG_RUNTIME_USER` and
|
||||
`THT_CATALOG_RUNTIME_PASSWORD_FILE`. Migration uses the corresponding migrator
|
||||
user/password file. Direct URL environments can use `THT_CATALOG_DATABASE_URL`
|
||||
(runtime) and `THT_CATALOG_MIGRATOR_DATABASE_URL`; the harness also accepts
|
||||
`THT_CATALOG_RUNTIME_DATABASE_URL`. Credentials are not authored in workspace YAML.
|
||||
|
||||
- selected: `tht memory save-one` runs, followed by a `memory_promoted` record;
|
||||
- deselected: records `memory_promotion_declined`;
|
||||
- no candidates: F8 closes automatically.
|
||||
The migration grants the installation login membership in the restricted
|
||||
`thoth_memory_runtime` role. Every repository transaction sets that role and a
|
||||
workspace context. Forced row-level policies isolate cards, links, dependencies
|
||||
and projection operations. This role has Memory DML and migration-status read
|
||||
access, with no runtime DDL privilege. There are no cascading foreign keys to
|
||||
Catalog or Evidence. A missing or incompatible schema returns a clear operational
|
||||
error. Preparation is repeatable and checks migration checksums.
|
||||
|
||||
The `memory_promoted` marker uses `detail: seq:N`, a reference to the original `concept_clarified` decision. The flow is in [harness/.pi/extensions/tht-gate.js](https://git.tylconsulting.it/mptyl/ThothII/src/branch/main/harness/.pi/extensions/tht-gate.js#L1691).
|
||||
|
||||
Promotion does not run in F2, and the model cannot invent F8 candidates. Direct promotion commands are also protected by the anti-bypass gate.
|
||||
|
||||
## Global persistence
|
||||
|
||||
### JSONL registry
|
||||
|
||||
The current registry is:
|
||||
|
||||
```text
|
||||
<artifacts>/memory/registry.jsonl
|
||||
```
|
||||
|
||||
The registry is written through a temporary file and `os.replace`, so replacement is atomic. Promotion is idempotent on the `session_id + decision_seq` pair: the same decision from the same session cannot create two global records.
|
||||
|
||||
### Qdrant
|
||||
|
||||
After promotion, `save-one` builds one `VectorRecord` and sends it to the Qdrant index. The indexed text includes:
|
||||
|
||||
- type and subject;
|
||||
- detail;
|
||||
- rationale;
|
||||
- question context;
|
||||
- any concepts and mappings.
|
||||
|
||||
The vector record uses the ID `memory:mem-XXXX`. Its metadata stores `subject`, `detail`, `rationale`, `tables`, `concepts`, and the `kind` discriminator. The content's SHA-256 hash prevents embedding and upsert work when the text has not changed.
|
||||
|
||||
This behavior is implemented in
|
||||
[harness/tht/memory/core.py](https://git.tylconsulting.it/mptyl/ThothII/src/branch/main/harness/tht/memory/core.py).
|
||||
|
||||
### Current canonical source
|
||||
|
||||
The JSONL registry remains the application's canonical source, while Qdrant is a derived but persistent index. The workflow does not record decisions directly in the vector database. It uses Qdrant as a searchable projection of the registry and effective ledger.
|
||||
|
||||
## Reuse in F2
|
||||
|
||||
In a future session, F2 runs:
|
||||
|
||||
```text
|
||||
tht memory search "<question>" --session <id> --json
|
||||
```
|
||||
|
||||
The command:
|
||||
|
||||
1. creates an embedding for the question;
|
||||
2. searches the vector store for records with `kind=memory` only;
|
||||
3. resolves each hit in the JSONL registry through its `ref`;
|
||||
4. discards records missing from the registry;
|
||||
5. discards every type other than `concept_clarified`;
|
||||
6. excludes Memory already decided in the current session;
|
||||
7. returns results ordered by similarity.
|
||||
|
||||
Memory is never applied automatically. The model must present it in one `reviewer_decide` choice:
|
||||
|
||||
- a selected Memory item is recorded as a new `concept_clarified` in the current session;
|
||||
- the rationale must cite the original `mem-XXXX` ID;
|
||||
- a deselected Memory item means "do not apply it now", not "delete it globally".
|
||||
|
||||
If F2 is reopened, a deselected Memory item can be proposed again. `memory_rejected` remains supported for legacy decisions and sessions, but it is not the normal behavior for current F2 deselection.
|
||||
|
||||
## Effective ledger, rollback, and reopening
|
||||
|
||||
The ledger is append-only. Reopening and withdrawing decisions do not delete earlier rows, but they change which decisions are effective.
|
||||
|
||||
Memory helpers use `effective_decisions()` to:
|
||||
|
||||
- exclude withdrawn decisions;
|
||||
- ignore decisions from phases that became stale after a rollback;
|
||||
- prevent promotion of clarifications that are no longer valid.
|
||||
|
||||
The effective view is defined in [harness/tht/phase.py](https://git.tylconsulting.it/mptyl/ThothII/src/branch/main/harness/tht/phase.py#L82).
|
||||
|
||||
## Display in the session summary
|
||||
|
||||
The "Memories" section of the summary is projected at runtime from the session ledger; it is not a direct copy of the global registry.
|
||||
|
||||
The projection:
|
||||
|
||||
- shows approved Memory first;
|
||||
- then shows declined Memory;
|
||||
- resolves `seq:N` to the original `concept_clarified`;
|
||||
- hides markers whose original record is not `concept_clarified`;
|
||||
- hides subjects that match schema-linking tables;
|
||||
- hides standalone subjects shaped like `fact_*` or `dim_*`;
|
||||
- keeps table and field references when they are part of the conceptual explanation.
|
||||
|
||||
The logic is in [harness/tht/session/store.py](https://git.tylconsulting.it/mptyl/ThothII/src/branch/main/harness/tht/session/store.py#L237). The frontend renders a structured list and treats `subject`, `detail`, and `rationale` as Markdown instead of showing raw Markdown.
|
||||
|
||||
The transformation happens on read. Historical sessions use the current layout and filters without rewriting their original artifacts.
|
||||
|
||||
## Enforced invariants
|
||||
|
||||
The protections are distributed across several boundaries:
|
||||
|
||||
1. `REUSABLE_TYPES` in the Python core;
|
||||
2. the `memory search` command filter;
|
||||
3. the F8 preview filter;
|
||||
4. filtering and deduplication in the Pi gate;
|
||||
5. exclusion of table Memory from the UI projection.
|
||||
|
||||
This prevents one prompt or component change from reintroducing tables as Memory.
|
||||
|
||||
## Remaining limits and risks
|
||||
|
||||
### The registry and index are not one transaction
|
||||
|
||||
Saving broadly follows this sequence:
|
||||
|
||||
```text
|
||||
JSONL registry → Qdrant → memory_promoted marker in the ledger
|
||||
```
|
||||
|
||||
If Qdrant is unavailable, the registry can contain Memory that is not yet searchable. The command reports that reindexing is required.
|
||||
|
||||
If the ledger marker fails after the vector database save, the Memory item can exist globally without a complete session audit. The gate returns a manual recovery command.
|
||||
|
||||
### Five-candidate limit
|
||||
|
||||
F8 proposes at most five Memory items. If a session produces more than five valid concepts, the extra items are not shown and the session can be finalized without promoting them.
|
||||
|
||||
### Deduplication is not global
|
||||
|
||||
Deduplication prevents duplicates within one proposal, and idempotency prevents the same decision from being promoted twice. There is no global merge of semantically similar Memory items from different sessions.
|
||||
|
||||
### Old physical records
|
||||
|
||||
Old `table_promoted` or `table_excluded` records may still exist in historical artifacts or indexes. The current code makes them unusable by filtering by type and does not show them in session projections. Physically removing them from the vector database remains a separate cleanup task.
|
||||
|
||||
## Final assessment
|
||||
|
||||
The current implementation matches the functional requirement: Memory is reusable conceptual knowledge, not a schema-linking choice.
|
||||
|
||||
The strongest part is the multilayer protection of the `concept_clarified` type. The main technical debt is the coexistence of the JSONL registry and Qdrant, with no single transaction spanning the global archive, semantic index, and session ledger.
|
||||
See [the M1 specification](plans/2026-09-08-memory-m1-spec.md) and
|
||||
[ADR 0018](adr/0018-use-postgres-for-memory-and-qdrant-for-retrieval.md) for the
|
||||
approved scope and acceptance boundaries.
|
||||
See [M2 implementation and validation](plans/2026-09-09-memory-m2-validation.md)
|
||||
for the retrieval checks and real embedding test command.
|
||||
|
||||
@@ -0,0 +1,492 @@
|
||||
# Progetto: Evidence management
|
||||
|
||||
Data: 2026-09-08. Stato: archivio locale Markdown, editor esterni e consolidamento
|
||||
manuale con commit/push dell'operatore accettati per la release 0;
|
||||
restanti semplificazioni confermate, con chiarimenti su impatto core e controllo Git;
|
||||
E1, E2, E3 e il collegamento ai gate X1 implementati il 2026-09-09.
|
||||
Il contratto X1 è in [Session corrections](../contracts/archive-repair.md). Risultati e limiti in
|
||||
[E1 — validazione](2026-09-09-evidence-e1-validation.md) e
|
||||
[E2 — validazione](2026-09-09-evidence-e2-validation.md) e
|
||||
[E3 — validazione](2026-09-09-evidence-e3-validation.md).
|
||||
|
||||
La [revisione di semplicità](2026-09-08-memory-evidence-simplification-review.md)
|
||||
registra il riesame di Q1–Q15. Il flusso principale è draft scritta dallo specialista
|
||||
indipendentemente dall'installazione, raffinamento da parte del sistema e
|
||||
conservazione locale per uso e manutenzione. La proposta tecnica aggiornata
|
||||
distingue le fonti esterne dall'archivio canonico locale, evita PostgreSQL per le
|
||||
Evidence e toglie commit/push dal normale CRUD. La contemporaneità con attività core
|
||||
durante l'amministrazione non è più un requisito da supportare.
|
||||
|
||||
Il progetto rende consultabili le Evidence dall'applicazione e modificabili nei
|
||||
file locali tramite l'editor scelto dall'operatore.
|
||||
Segue le [decisioni comuni di Administration](2026-09-08-memory-evidence-administration.md)
|
||||
ed è consegnabile separatamente da [Memory management](2026-09-08-memory-management.md).
|
||||
|
||||
## Risultato richiesto
|
||||
|
||||
Un amministratore apre Evidence management direttamente da Administration, cerca e
|
||||
filtra le Evidence registrate, consulta il documento completo e trova il percorso
|
||||
del file Markdown da modificare con un editor esterno. La voce segue Memory management e si trova allo stesso
|
||||
livello di Database management, senza appartenere alle sue funzionalità.
|
||||
|
||||
La consultazione è indipendente da una sessione e dalla disponibilità dell'indice
|
||||
semantico. Mostra le Evidence Unit complete, senza limitarsi ai frammenti o ai
|
||||
risultati più simili restituiti dal recall.
|
||||
|
||||
## Accesso e modifica nella release 0
|
||||
|
||||
Il proprietario richiede file facilmente raggiungibili e modificabili anche da uno
|
||||
specialista non tecnico, con Markdown come formato di lavoro e senza JSONL per la
|
||||
gestione delle Evidence. Ha scelto editor esterni per la release 0: l'editor
|
||||
preferito sul Mac o PC, oppure vim, nano o equivalenti sul server. Questa scelta
|
||||
sostituisce la proposta di editor e form di contenuto dentro Evidence management.
|
||||
Non si integra un prodotto di editing né si costruisce un editor applicativo.
|
||||
|
||||
Evidence management mantiene elenco, ricerca, filtri e dettaglio. Mostra il percorso
|
||||
assoluto della cartella del workspace e di ciascun file, con possibilità di copiarlo,
|
||||
risolto dalla configurazione effettiva dell'installazione. Indica su quale host si
|
||||
trova: per Docker occorre il percorso persistente accessibile sull'host, non soltanto
|
||||
quello interno al container. Le istruzioni distinguono draft originali e file delle
|
||||
Evidence raffinate da manutenere; includono un esempio Markdown per crearne una.
|
||||
|
||||
Chi lavora sul server modifica direttamente i file; chi lavora su una copia sul
|
||||
Mac o PC la riporta nello stesso archivio con i propri strumenti. Non è richiesto
|
||||
costruire upload/download nell'applicazione o predisporre una cartella condivisa.
|
||||
Un percorso sul server non viene presentato come un file apribile dal browser locale.
|
||||
|
||||
Dopo aver salvato, aggiunto o rimosso i file, l'operatore controlla lo stato Git,
|
||||
esegue il consolidamento ed esegue commit e push; il normale diff Git è disponibile
|
||||
per approfondire le modifiche. La pagina mostra
|
||||
le istruzioni e i comandi con i percorsi effettivi. La richiesta più recente
|
||||
sostituisce la proposta intermedia del pulsante `Apply file changes`: non sono
|
||||
necessari un pulsante di esecuzione, watcher o operazioni Git automatiche.
|
||||
Il semplice salvataggio nell'editor, o di una copia fuori dall'archivio, non aggiorna
|
||||
il recall. Il consolidamento e il seguito Git sono descritti sotto.
|
||||
|
||||
Il Markdown canonico attuale non è già un formato di editing libero: il parser
|
||||
controlla marker e corrispondenza fra testo canonico e presentazione. Per le regole
|
||||
di dominio il testo codificato viene letto prima di verificare il rendering; cambiare
|
||||
la sola frase visibile può produrre un errore di canonicalità. E1 deve quindi rendere
|
||||
il Markdown locale realmente editabile: il testo leggibile è autorevole, i campi
|
||||
richiesti sono documentati e i metadati derivati sono aggiornati dal sistema.
|
||||
Non si chiede all'operatore di correggere marker, hash o una copia codificata del
|
||||
testo. Non si introduce un secondo archivio di scambio da sincronizzare.
|
||||
|
||||
## Funzioni
|
||||
|
||||
- Elenco paginato e ordinabile; ricerca per testo, titolo e identificatore stabile.
|
||||
- Filtri combinabili per workspace, kind, purpose, concetti, tabelle/colonne,
|
||||
Source Evidence, Review item e stato di pubblicazione.
|
||||
- Dettaglio leggibile della card: contenuto tipizzato, ambito di applicazione,
|
||||
Supporting excerpt, provenienza e accesso alla Source Evidence disponibile.
|
||||
- Creazione e modifica tramite file Markdown ed editor esterno, con esempio dei
|
||||
campi richiesti per kind. In assenza di documento esterno, l'applicazione registra
|
||||
una dichiarazione manuale come fonte quando acquisisce la modifica.
|
||||
- Risoluzione dei Review item e gestione delle unità orfane o da ritirare.
|
||||
- Cancellazione tramite rimozione del file, riconosciuta dal consolidamento
|
||||
nell'archivio locale verificato come accessibile; un errore di lettura non prova
|
||||
una cancellazione. La rimozione dal corpus e dall'indice è persistente.
|
||||
- Un comando manuale di consolidamento per acquisire e validare le modifiche locali
|
||||
e renderle disponibili al core, con esito esplicito e possibilità di riesecuzione.
|
||||
- Istruzioni per controllo del diff, commit e push dei file Evidence e dei relativi
|
||||
metadati necessari, eseguiti dall'operatore nel repository indicato.
|
||||
|
||||
Il servizio acquisisce il Markdown editabile e aggiorna la rappresentazione
|
||||
tipizzata e i metadati derivati, preservando gli identificatori delle unità esistenti.
|
||||
La cancellazione di una Evidence Unit non elimina automaticamente la sua Source
|
||||
Evidence o altre unità derivate dalla stessa fonte.
|
||||
|
||||
## Salvataggio — Q12 semplificata
|
||||
|
||||
Il proprietario rifiuta la separazione ordinaria fra salvataggio della bozza e
|
||||
pubblicazione: le modifiche durante una sessione sono considerate rare e non
|
||||
giustificano un workflow editoriale separato. La scelta successiva dell'editor esterno
|
||||
sostituisce il `Save` della form con il salvataggio del file e un comando manuale
|
||||
di consolidamento. Questo acquisisce, valida e attiva insieme aggiunte, modifiche e
|
||||
cancellazioni, senza un successivo `Publish` o un secondo revisore. Commit e push
|
||||
sono il seguito manuale per versionare e trasferire il lavoro nel repository.
|
||||
L'operatore autorizza l'attivazione con il consolidamento. Le correzioni approvate nei
|
||||
gate chiamano direttamente lo stesso servizio e non richiedono un editor esterno.
|
||||
|
||||
L'ultimo chiarimento del proprietario sostituisce il requisito iniziale di aggiornare
|
||||
le sessioni aperte mentre un amministratore modifica le Evidence. Si assume che il
|
||||
core sia fermo o si ignora la contemporaneità: non servono aggiornamenti a caldo,
|
||||
notifiche, ricalcoli, attese delle sessioni o una modalità manutenzione dedicata.
|
||||
Il risultato di una modifica completata è usato nelle successive elaborazioni.
|
||||
|
||||
Restano le correzioni deliberate dalla sessione stessa secondo Q4: chiamano lo
|
||||
stesso servizio, attendono l'esito e permettono alla sessione di usare la correzione
|
||||
approvata. Il collegamento fra configurazione della ricerca e contenuto locale
|
||||
deve quindi funzionare senza richiedere un nuovo commit della fonte per ogni modifica;
|
||||
non richiede un sistema generale di aggiornamento delle altre sessioni.
|
||||
|
||||
Nel seguito, salvataggio applicativo indica questa acquisizione delle modifiche o
|
||||
la scrittura deliberata dal core. Il feedback ordinario è operazione in corso,
|
||||
completata oppure errore. Un successo
|
||||
completo significa che il contenuto è disponibile al core; se la persistenza riesce
|
||||
ma l'aggiornamento del corpus o dell'indice fallisce, l'esito deve dirlo e indicare
|
||||
come rieseguire il comando. Un errore tecnico non diventa una bozza che attende una nuova decisione
|
||||
editoriale di pubblicazione. Dopo un errore o un riavvio, un corpus parziale non
|
||||
deve essere dichiarato pronto per la successiva elaborazione.
|
||||
|
||||
Le decisioni Q11–Q15 e il successivo chiarimento sui vincoli sono registrati
|
||||
nell'[ADR 0019](../adr/0019-author-evidence-in-app-with-automatic-activation.md).
|
||||
|
||||
## Consolidamento manuale e seguito Git — release 0 {#consolidamento-manuale-e-seguito-git--release-0}
|
||||
|
||||
Il proprietario richiede un flusso KISS affidato alla disciplina dell'operatore.
|
||||
Il comando proposto è `tht evidence consolidate <workspace-root>` nel harness:
|
||||
è da implementare, non è un comando già disponibile. Riutilizza parser, validazione
|
||||
e indicizzazione esistenti, adattati al Markdown editabile. La documentazione
|
||||
operativa e la pagina mostreranno l'invocazione effettiva per l'installazione,
|
||||
compreso l'accesso al core se il comando gira in Docker.
|
||||
|
||||
Il consolidamento svolge in sequenza questi passaggi:
|
||||
|
||||
1. Legge l'archivio locale e confronta aggiunte, modifiche e rimozioni con l'ultimo
|
||||
contenuto consolidato. Se l'archivio non è accessibile, si ferma: non interpreta
|
||||
il problema come cancellazione delle Evidence.
|
||||
2. Verifica struttura e sezioni previste per kind, campi obbligatori, identificatori
|
||||
univoci, tipi, riferimenti e provenienza coerenti. Segnala file, campo o sezione,
|
||||
problema e correzione richiesta. Non valuta automaticamente la verità del contenuto
|
||||
e non riscrive il significato delle regole con un nuovo raffinamento del modello.
|
||||
3. Se ci sono errori, termina con esito non riuscito prima dell'attivazione; lascia
|
||||
all'operatore i file da correggere e il comando da rieseguire. Se i controlli
|
||||
passano, aggiorna metadati derivati e manifest, inclusa la protezione delle
|
||||
correzioni e delle cancellazioni, poi prepara e verifica il candidato completo
|
||||
prima di renderlo attivo nel corpus e nell'indice Evidence locale.
|
||||
4. Riporta un riepilogo testuale breve di file aggiunti, modificati e cancellati,
|
||||
l'esito locale, gli eventuali errori di indicizzazione e i file primari
|
||||
da includere nel commit. Dopo un errore tecnico si riesegue lo stesso comando,
|
||||
senza duplicare unità o perdere il contenuto modificato. Non dichiara pronto un
|
||||
aggiornamento incompleto e non avvia commit, push, pull o merge.
|
||||
|
||||
Il core legge soltanto il contenuto consolidato attivo, mai direttamente i file in
|
||||
corso di modifica. Una modifica salvata ma non consolidata, o un tentativo fallito,
|
||||
non deve mescolare testo nuovo e vecchi risultati di ricerca. Si conserva l'ultimo
|
||||
corpus valido; se un errore tecnico non permette di garantirne l'integrità, si
|
||||
segnala l'indisponibilità invece di usare uno stato parziale. Si riusa il percorso
|
||||
esistente di preparazione del candidato e attivazione, senza creare un secondo
|
||||
archivio autorevole o un sistema di coordinamento delle sessioni.
|
||||
|
||||
L'archivio mantenuto è una working tree persistente, versionabile nel repository
|
||||
che contiene quelle Evidence; può riusare il repository del workspace. Draft e
|
||||
unità curate restano contenuti distinti anche se ospitati nello stesso repository.
|
||||
Non si modifica una materializzazione temporanea o uno snapshot runtime ricreato
|
||||
dal preprocessing. Setup e pagina indicano working tree, cartella delle Evidence,
|
||||
branch e remoto configurati; non si creano automaticamente repository o remoti.
|
||||
|
||||
Il seguito manuale, documentato come sequenza da eseguire nel repository corretto, è:
|
||||
|
||||
```text
|
||||
git -C <repository-root> status --short
|
||||
tht evidence consolidate <workspace-root> # comando previsto, da implementare
|
||||
git -C <repository-root> add -- <file-evidence-e-metadati-indicati>
|
||||
git -C <repository-root> commit -m "Update Evidence"
|
||||
git -C <repository-root> push
|
||||
```
|
||||
|
||||
Il controllo umano usa i normali comandi Git nel terminale. `git status --short`
|
||||
mostra quali file sono cambiati; `git diff HEAD` permette, quando serve, di vedere
|
||||
le righe cambiate prima del consolidamento. `git diff --cached` è disponibile per
|
||||
controllare ciò che si sta per committare. Non sono richiesti un visualizzatore
|
||||
nell'applicazione, uno strumento grafico, due revisioni obbligatorie o un nuovo gate.
|
||||
I controlli strutturali del consolidamento vengono invece sempre eseguiti.
|
||||
|
||||
Si includono aggiunte, modifiche e cancellazioni dei dati primari necessari alla
|
||||
ricostruzione, compresi manifest e informazioni di cura manuale quando cambiano.
|
||||
Indici, cache, sessioni e segreti non fanno parte del commit Evidence. L'operatore
|
||||
controlla aggiunte, modifiche e cancellazioni prima di consolidare; i file nuovi
|
||||
segnalati da status vanno letti, perché non compaiono ancora nel diff dei file
|
||||
tracciati. L'output del consolidamento indica anche i metadati generati da includere
|
||||
nel commit. Errori Git, credenziali, branch senza upstream e conflitti vengono
|
||||
risolti con i normali strumenti Git, senza retry o risoluzioni automatiche.
|
||||
|
||||
L'ordine ha una conseguenza esplicita: un consolidamento riuscito aggiorna il core
|
||||
locale prima di commit e push. Se il push manca o fallisce, la modifica rimane locale
|
||||
e non è ancora trasferita al remoto; l'operatore completa il seguito Git. Un push
|
||||
riuscito, da solo, non aggiorna altre installazioni. Nessun processo sorveglia i file
|
||||
o impone che l'operatore abbia completato la sequenza prima di riprendere il lavoro.
|
||||
|
||||
## Persistenza e contratto da evolvere
|
||||
|
||||
Il proprietario ha approvato la risoluzione persistente dei conflitti fra Memory ed
|
||||
Evidence nel round Q4 della discussione Memory. Quando la decisione richiede correggere
|
||||
un'Evidence, il core prepara una proposta che identifica l'unità e mostra il testo
|
||||
o l'ambito risultante. La correzione passa attraverso l'authoring e la pubblicazione
|
||||
di questo modulo, con le relative autorizzazioni e validazioni. L'accettazione della
|
||||
correzione da parte di un utente autorizzato avvia lo stesso salvataggio con attivazione
|
||||
automatica. L'interfaccia distingue una proposta da approvare, un aggiornamento in
|
||||
corso o fallito e una correzione già attiva; non basta risolvere soltanto
|
||||
la domanda corrente. È sempre possibile dichiarare inadeguate le opzioni proposte.
|
||||
|
||||
Oggi il [lifecycle Evidence](../evidence.md) attribuisce l'authoring al repository
|
||||
del workspace: ThothII non lo modifica, non crea commit e non esegue push.
|
||||
Il [contratto Workspace Evidence v3](../contracts/workspace-evidence-v3.md) lega la
|
||||
pubblicazione a una revisione coerente del workspace. La manutenzione dei file locali
|
||||
richiede un'evoluzione esplicita di questo percorso e del formato editabile.
|
||||
|
||||
**Q11, riesaminata e accettata per l'archivio locale:** la draft dello specialista deve restare producibile e
|
||||
consegnabile senza accesso al PostgreSQL o alla stessa installazione. La
|
||||
scelta aggiornata conserva le fonti in file/repository esterni e le
|
||||
Evidence raffinate in un archivio locale persistente su file Markdown, gestito dal sistema.
|
||||
Il CRUD modifica tale archivio e aggiorna l'indice senza commit/push verso le fonti.
|
||||
L'alternativa di rendere PostgreSQL autorevole anche per Evidence, suggerita nella
|
||||
prima parte della revisione, è ritirata. PostgreSQL rimane l'archivio delle Memory.
|
||||
|
||||
I file locali curati sono dati primari: sopravvivono a Clear e reindicizzazione e
|
||||
devono essere inclusi nelle copie di sicurezza dell'installazione. Una loro modifica
|
||||
non aggiorna automaticamente i documenti dello specialista o altre installazioni;
|
||||
un eventuale trasferimento dei file resta esplicito, senza sincronizzazione bidirezionale.
|
||||
|
||||
Il comportamento deve coprire le origini supportate dal prodotto: filesystem/Git,
|
||||
HTTP e S3. Nella proposta riveduta sono origini di acquisizione delle fonti e dei
|
||||
contenuti già disponibili. Servono importazione e provenienza coerenti; le unità
|
||||
raffinate e le modifiche manuali vengono conservate nell'archivio locale.
|
||||
La gestione delle Evidence non richiede di aggiungere scritture sui server HTTP o S3
|
||||
di origine. Non si può dichiarare completato il CRUD lasciando queste unità in sola
|
||||
lettura senza un percorso di importazione utilizzabile.
|
||||
|
||||
Il descriptor `evidence.source` indica oggi l'origine acquisita dal preprocessing:
|
||||
non è già un importatore di documenti nel repository di authoring. Inoltre il
|
||||
runtime normalizza HTTP/S3 come documenti generici, mentre il parser canonico delle
|
||||
unità tipizzate viene applicato ai file sotto `curated/<kind>/`. La provenienza
|
||||
canonica ammette solo un percorso locale sotto `source/`; URI e fingerprint remoti
|
||||
esistono invece nel corpus acquisito. L'importazione deve collegare questi due
|
||||
livelli senza fingere che il percorso tipizzato sia già uniforme fra i trasporti.
|
||||
|
||||
Modifiche e ritiri devono sopravvivere alla successiva preparazione, sincronizzazione
|
||||
e reindicizzazione. La rigenerazione da una fonte non deve ripristinare silenziosamente
|
||||
una unità cancellata o sovrascrivere la correzione del curatore. La semantica di
|
||||
conflitto fra nuova Source Evidence e cura manuale è approvata in Q13.
|
||||
|
||||
Il runtime attuale non garantisce questa protezione durevole: `evidence prepare`
|
||||
rifiuta modifiche non committate ai file curati e al manifest, ma una fonte cambiata
|
||||
può rigenerare anche unità corrette manualmente e già committate. Il ritiro esplicito
|
||||
rimuove l'unità e i riferimenti nel manifest, senza conservare una soppressione che
|
||||
impedisca a una successiva generazione di riproporla. Questi comportamenti sono
|
||||
verificati in `harness/tht/evidence/authoring.py`; la gestione amministrativa richiede
|
||||
di evolverli, non solo di esporli come comandi dell'editor.
|
||||
|
||||
**Q13, approvata:** se la fonte aggiornata contraddice una correzione
|
||||
manuale, conservare in uso l'Evidence salvata dall'amministratore e mostrare il
|
||||
confronto in Evidence management. Una sostituzione richiede una scelta esplicita,
|
||||
seguita dalla stessa operazione di attivazione. La conseguenza è che la regola manuale può restare
|
||||
attiva anche se la fonte più recente dice altro, finché il conflitto non viene
|
||||
risolto. Il proprietario accetta questa conseguenza. La decisione comprende la
|
||||
permanenza delle cancellazioni e la protezione da sovrascritture silenziose: una
|
||||
nuova preparazione non deve riproporre automaticamente conoscenze eliminate.
|
||||
|
||||
Validazione e pubblicazione sono passaggi interni dell'unica operazione di salvataggio;
|
||||
un errore non dichiara attivo il nuovo contenuto. Il sistema continua a rispettare
|
||||
provenienza e coerenza del contenuto; il salvataggio esplicito dell'amministratore
|
||||
costituisce l'approvazione della modifica manuale. La decisione sullo storico delle
|
||||
Memory non elimina questi requisiti del dominio Evidence.
|
||||
|
||||
## Creazione manuale e aggiornamento delle fonti — Q14 e Q15 approvate
|
||||
|
||||
**Q14, approvata:** consentire di scrivere una
|
||||
Evidence senza dover fornire un documento esterno. In release 0 la si scrive in un
|
||||
nuovo file Markdown nell'archivio indicato, usando l'esempio documentato.
|
||||
Il sistema registra una dichiarazione manuale come fonte gestita e la distingue
|
||||
dall'informazione derivata da documenti. Lo stesso criterio vale per una correzione
|
||||
che cambia il significato del contenuto: la dichiarazione dell'amministratore
|
||||
sostiene il testo corrente, mentre il documento originario resta collegato come
|
||||
origine e per rilevarne gli aggiornamenti. Non deve essere mostrato come prova di
|
||||
una regola che non contiene. Il consolidamento acquisisce anche le nuove unità manuali.
|
||||
|
||||
Oggi la provenienza canonica richiede fonte locale, hash ed estratti: non esiste
|
||||
un'origine manuale esplicita. La validazione verifica integrità e presenza testuale
|
||||
degli estratti, ma non dimostra la verità o il supporto semantico della regola.
|
||||
Attuare Q14 richiede distinguere nel contratto la fonte del testo corrente dal
|
||||
documento originario; non richiede inventare estratti o una validazione semantica
|
||||
automatica presentata come garanzia di correttezza.
|
||||
|
||||
**Q15, approvata:** riacquisire le fonti esterne su richiesta
|
||||
esplicita dell'amministratore, senza controlli periodici o accessi alle fonti a ogni
|
||||
domanda o salvataggio di una card. Fra due aggiornamenti richiesti, il sistema usa
|
||||
quanto già acquisito. Il consolidamento continua ad attivare la modifica locale
|
||||
senza richiedere prima un aggiornamento della fonte remota; eventuali conflitti
|
||||
scoperti alla successiva acquisizione seguono Q13.
|
||||
|
||||
Il proprietario ha approvato entrambe le raccomandazioni il 2026-09-08. Il successivo
|
||||
riesame conserva questi comportamenti e rende esplicita l'autonomia dello specialista
|
||||
che produce le draft. I dettagli tecnici seguenti descrivono la proposta semplificata.
|
||||
|
||||
## Piano esecutivo
|
||||
|
||||
### E1 — Raffinamento e archivio canonico locale
|
||||
|
||||
**Modifica del sottosistema Evidence core.** Rendere editabile il Markdown cambia
|
||||
il contratto che il codice attuale legge e scrive. Questa attività precede la
|
||||
pagina amministrativa: non è una modifica limitata alla presentazione o all'editor.
|
||||
Il nuovo formato conserva contenuti tipizzati, ambito e provenienza richiesti dal
|
||||
core, ma usa il testo visibile come unica rappresentazione autorevole del contenuto
|
||||
umano. Va identificato come una nuova versione del contratto Curated unit, distinta
|
||||
dalla versione del descriptor del workspace.
|
||||
|
||||
L'intervento coordinato comprende:
|
||||
|
||||
- parser, renderer e validazione in `harness/tht/evidence/canonical.py`;
|
||||
- preparazione, scritture e migrazione in `harness/tht/evidence/authoring.py`,
|
||||
con adeguamento delle istruzioni e degli esempi usati nel raffinamento;
|
||||
- acquisizione e normalizzazione in `harness/tht/evidence/corpus/normalize.py`,
|
||||
consolidamento e preprocessing, affinché producano il contenuto tipizzato atteso
|
||||
dall'indicizzazione e dal recall;
|
||||
- correzioni deliberate dal core, provenienza e citazioni, che devono consumare
|
||||
e aggiornare coerentemente la nuova rappresentazione;
|
||||
- contratto documentato e test del percorso completo: modifica del testo visibile,
|
||||
consolidamento, contenuto indicizzato e successivo utilizzo da parte del core.
|
||||
|
||||
Le Evidence esistenti devono essere convertite esplicitamente al nuovo formato
|
||||
e reindicizzate, verificando il mantenimento del contenuto e degli identificatori.
|
||||
La fase di sviluppo permette un passaggio unico; non è richiesto mantenere due
|
||||
formati di authoring concorrenti. Una conversione non rappresentabile fedelmente
|
||||
va segnalata. Si preserva il modello tipizzato interno dove possibile, per contenere
|
||||
la modifica nei componenti che dipendono dal documento senza ridisegnare le fasi
|
||||
del workflow NL→SQL.
|
||||
|
||||
Estendere i contratti in `harness/tht/evidence/` per distinguere fonte corrente,
|
||||
dichiarazione manuale e documento originario. La dichiarazione viene gestita
|
||||
dall'applicazione insieme all'unità locale; chi scrive il Markdown non deve
|
||||
creare un file sorgente separato o gestire hash ed estratti. I campi per kind
|
||||
mantengono la validazione deterministica, senza attribuirle una verifica della
|
||||
verità della regola. Aggiornare il glossario e il contratto canonico con il codice.
|
||||
|
||||
Riutilizzare raffinamento, parser, renderer e validazione esistenti, distinguendo
|
||||
la working tree locale persistente dagli snapshot acquisiti e adattando il formato al testo Markdown
|
||||
editabile come fonte autorevole, senza duplicazione nascosta del contenuto umano.
|
||||
Documentare posizione dei file, campi richiesti e un esempio per la creazione.
|
||||
L'applicazione acquisisce le draft e
|
||||
conserva il risultato in file locali persistenti. Le mutazioni aggiornano contenuto
|
||||
canonico, presentazione Markdown e manifest; le scritture sono serializzate per
|
||||
workspace e controllano la versione corrente del record; una modifica concorrente
|
||||
non viene risolta sovrascrivendo silenziosamente il contenuto altrui.
|
||||
|
||||
Il salvataggio non richiede commit, push o un database condiviso con lo specialista.
|
||||
L'archivio locale è distinto dalla materializzazione runtime ricostruita da Git e
|
||||
dal corpus derivato. Consolidamento e preprocessing acquisiscono i contenuti locali
|
||||
curati; il core consulta soltanto il corpus attivo validato. Clear preserva i file
|
||||
e la ricostruzione dell'indice riparte da essi, senza sovrascriverli
|
||||
con nuove copie delle draft originali.
|
||||
|
||||
La persistenza conserva la cura manuale e le esclusioni necessarie a impedire la
|
||||
ricomparsa delle unità eliminate. La rigenerazione confronta le proposte con tale
|
||||
stato: assegnare un nuovo ID a un contenuto derivato non deve essere un modo per
|
||||
riattivarlo automaticamente aggirando una cancellazione. Le nuove proposte e i
|
||||
conflitti restano distinti dal corpus già approvato e attivo.
|
||||
|
||||
Verificare con archivi locali temporanei draft esterne e raffinamento, creazione
|
||||
manuale, cambiamento di significato
|
||||
con provenienza corretta, round trip del formato canonico, aggiornamento del manifest,
|
||||
cancellazione, conflitto fra scritture e retry. La validazione di un estratto
|
||||
presente nella fonte non viene usata come prova automatica di supporto semantico.
|
||||
|
||||
### E2 — Pagina amministrativa e consolidamento manuale
|
||||
|
||||
Esporre API amministrative per elenco completo, filtri, dettaglio, mutazioni ed
|
||||
esito delle operazioni. Il backend applica autorizzazioni e isolamento, poi chiama
|
||||
il servizio di authoring del harness. Realizzare la pagina autonoma nell'AppShell
|
||||
con provenienza leggibile, percorsi effettivi dei file sull'host e istruzioni per
|
||||
modificarli con editor esterni, consolidarli e completare commit/push manualmente.
|
||||
Il comando di consolidamento acquisisce aggiunte, modifiche e rimozioni locali
|
||||
tramite lo stesso servizio. Nessun editor, form di contenuto o
|
||||
trasferimento file web è richiesto in R0; non serve una sessione del core.
|
||||
|
||||
Evolvere lo stage interno `runEvidenceStage` e il percorso harness
|
||||
`tht preprocess evidence` per attivare il contenuto canonico locale autorizzato.
|
||||
Il salvataggio non avvia una riacquisizione HTTP/S3, una nuova estrazione dalle
|
||||
Source Evidence o una scansione DWH. Il nuovo comando manuale Evidence riusa questo
|
||||
stage interno senza richiedere un preprocessing completo per ogni modifica.
|
||||
|
||||
Preparare e verificare il candidato Evidence prima di attivarlo. L'indicizzazione
|
||||
e la rimozione devono essere circoscritte al workspace e alle generazioni Evidence
|
||||
interessate nella collezione Reference condivisa. Preservare Schema, relazioni,
|
||||
LSH e Memory: il salvataggio non usa Preprocessing Clear e non ricrea l'intera
|
||||
collezione. Se l'attivazione fallisce, mostrare l'esito parziale e rendere ripetibile
|
||||
il completamento della stessa modifica, senza chiedere una nuova approvazione.
|
||||
|
||||
Adeguare la ricerca perché consumi l'archivio locale aggiornato, senza richiedere
|
||||
commit della fonte o cambiare configurazioni estranee. Adeguare il calcolo della
|
||||
readiness: aggiornare Evidence non dichiara risolto un blocco
|
||||
di Schema o Catalog. Dopo un Clear, l'eventuale necessità di preprocessing completo
|
||||
rimane esplicita; il solo consolidamento non ricostruisce tutti i derivati mancanti.
|
||||
|
||||
Verificare che i percorsi mostrati portino ai file effettivi anche su installazioni
|
||||
Docker e che una modifica alla frase visibile sia acquisita senza editing di metadati
|
||||
tecnici. Verificare creazione/modifica/cancellazione con esito disponibile al core, errore
|
||||
di indicizzazione dopo persistenza, retry e isolamento delle altre componenti
|
||||
della collezione. Le successive elaborazioni devono usare il contenuto corrente
|
||||
senza recuperare unità cancellate. Verificare le correzioni deliberate dalla sessione
|
||||
stessa, senza aggiungere prove di CRUD amministrativo concorrente al core. Un
|
||||
problema preesistente di Catalog deve continuare a impedire una falsa readiness.
|
||||
Verificare che errori strutturali impediscano l'attivazione e producano indicazioni
|
||||
correggibili, che il comando sia rieseguibile e che non esegua operazioni Git.
|
||||
Verificare che file modificati senza consolidamento e tentativi falliti non cambino
|
||||
il contenuto usato dal core né combinino versioni differenti di testo e indice.
|
||||
Provare la sequenza documentata di commit/push con repository temporanei e remoto
|
||||
locale, verificando l'inclusione delle cancellazioni e dei metadati necessari.
|
||||
|
||||
### E3 — Importazione, refresh esplicito e conflitti con le fonti
|
||||
|
||||
Fornire un percorso di importazione locale per le origini già supportate,
|
||||
conservando contenuto acquisito e provenienza remota. Uniformare il passaggio alle
|
||||
unità canoniche: i documenti HTTP/S3 oggi normalizzati genericamente devono diventare
|
||||
file locali editabili. Le unità importate restano gestibili senza credenziali di
|
||||
scrittura sui server fonte.
|
||||
|
||||
L'azione amministrativa di aggiornamento delle fonti riacquisisce il contenuto e
|
||||
confronta le impronte con quanto già acquisito. Per le unità curate interessate,
|
||||
prepara il confronto con le proposte risultanti senza sostituire la dichiarazione
|
||||
manuale attiva. Questa protezione non dipende dalla capacità del modello di
|
||||
riconoscere ogni contraddizione semantica. La scelta dell'amministratore usa poi
|
||||
lo stesso salvataggio con attivazione; fonti invariate non richiedono nuova cura.
|
||||
|
||||
Verificare con origini controllate che la riacquisizione avvenga soltanto su richiesta,
|
||||
che un errore di accesso non venga scambiato per una cancellazione e che consolidamento/recall
|
||||
non chiamino i connettori di acquisizione remota. Verificare aggiornamento di una
|
||||
fonte collegata a una correzione manuale, permanenza della versione curata, decisione
|
||||
di sostituzione e mancata ricomparsa automatica delle unità eliminate.
|
||||
|
||||
La lettura può essere consegnata come incremento intermedio di E2, ma il progetto
|
||||
è completo soltanto con CRUD, attivazione e gestione delle origini previste. X1 nel
|
||||
piano comune collega le proposte provenienti dai conflitti con Memory e verifica
|
||||
che raggiungano questi stessi servizi con autorizzazioni ed esiti coerenti.
|
||||
|
||||
## Criteri di completamento
|
||||
|
||||
- Tutte le unità sono raggiungibili mediante elenco e filtri, senza una sessione.
|
||||
- La pagina mostra cartella e percorso effettivo sull'host per ogni unità. Markdown,
|
||||
campi richiesti ed esempi permettono creazione e modifica con editor esterni;
|
||||
i dati invalidi non vengono attivati e gli errori indicano il file da correggere.
|
||||
- Una draft prodotta fuori dall'installazione può essere acquisita, raffinata e
|
||||
conservata localmente senza accesso dello specialista a PostgreSQL.
|
||||
- Creazione, modifica e ritiro aggiornano l'archivio locale e il corpus usato dal core;
|
||||
non richiedono commit/push nel repository delle fonti.
|
||||
- Una Evidence può essere creata senza documento esterno; la dichiarazione manuale
|
||||
è riconoscibile e il documento originario di una correzione non è mostrato come
|
||||
supporto di un'affermazione che non contiene.
|
||||
- Una modifica o cancellazione completata resta valida dopo una nuova preparazione
|
||||
e reindicizzazione; non rimangono frammenti ricercabili della versione rimossa.
|
||||
- Una fonte aggiornata in conflitto con la cura manuale non sostituisce l'Evidence
|
||||
attiva: il confronto resta disponibile all'amministratore fino alla sua decisione.
|
||||
- Il consolidamento manuale completa anche l'attivazione, senza un successivo `Publish`; l'esito
|
||||
distingue operazione in corso, completata ed eventuali errori con retry.
|
||||
- Il core usa soltanto l'ultimo corpus consolidato valido. File in lavorazione o
|
||||
consolidamenti falliti non diventano disponibili attraverso letture dirette.
|
||||
- Dopo una modifica completata, le successive elaborazioni recuperano il contenuto
|
||||
corrente. Dopo una cancellazione completata non recuperano l'unità rimossa.
|
||||
Nessuna delle due operazioni riscrive decisioni, artefatti o SQL già prodotti.
|
||||
- Clear e ricostruzione degli indici preservano le Evidence canoniche locali,
|
||||
incluse le correzioni e le esclusioni dovute a cancellazioni.
|
||||
- Le correzioni originate da conflitti con Memory raggiungono lo stesso percorso
|
||||
autorevole delle modifiche amministrative e mostrano il proprio stato di pubblicazione.
|
||||
- Le origini senza scrittura dispongono di un percorso utilizzabile verso l'authoring.
|
||||
- Le fonti esterne vengono riacquisite solo su richiesta dell'amministratore;
|
||||
il consolidamento e il recall usano il contenuto locale già acquisito.
|
||||
- API e pagina applicano accesso amministrativo e isolamento dei workspace.
|
||||
- Le istruzioni identificano working tree e file effettivi; il seguito manuale
|
||||
include verifica del diff, commit e push. Nessun watcher o comando Git automatico
|
||||
è introdotto. L'esito distingue disponibilità locale e trasferimento al remoto.
|
||||
- Il salvataggio delle Evidence preserva Memory, Schema, relazioni, LSH e Catalog
|
||||
Metadata; non elimina blocchi di readiness estranei all'aggiornamento Evidence.
|
||||
@@ -0,0 +1,261 @@
|
||||
# Amministrazione di Memory ed Evidence
|
||||
|
||||
Data del piano: 2026-09-08. Aggiornamento 2026-09-09: M1–M3, E1–E3 e X1
|
||||
implementati. Risultati e limiti della verifica finale sono raccolti nel
|
||||
[rapporto X1](2026-09-09-archive-repair-x1-validation.md).
|
||||
|
||||
La [revisione di semplicità](2026-09-08-memory-evidence-simplification-review.md)
|
||||
riesamina tutte le decisioni Q1–Q15 alla luce degli ultimi chiarimenti del
|
||||
proprietario e confronta le conseguenze con il piano precedente. Per Evidence R0
|
||||
sono scelti file Markdown locali, editor esterni e consolidamento manuale con
|
||||
controllo della struttura, seguito da diff, commit e push dell'operatore. La pagina
|
||||
deve indicare chiaramente percorsi e comandi. Le restanti semplificazioni sono
|
||||
confermate. Il cambio del formato richiede adeguare il sottosistema core Evidence,
|
||||
convertire i file e reindicizzare; E1 precede la pagina. Il controllo umano usa
|
||||
lo stato Git nel terminale, con diff delle righe quando serve, senza una UI dedicata.
|
||||
Si ignora la contemporaneità fra amministrazione e core. Lo
|
||||
specialista scrive draft indipendentemente dall'installazione; il sistema le
|
||||
raffina e le conserva localmente. La proposta aggiornata usa file canonici locali
|
||||
per le Evidence e toglie commit/push automatici dal CRUD; questa revisione tecnica di Q11
|
||||
sostituisce la raccomandazione precedente ed è stata attuata negli incrementi E1–E3.
|
||||
|
||||
## Obiettivo e decisioni del proprietario
|
||||
|
||||
L'amministratore deve poter accedere in qualsiasi momento alle Memory e alle Evidence
|
||||
registrate, cercarle, filtrarle, aprirle, crearle, modificarle e cancellarle. L'accesso
|
||||
non richiede una sessione del core o una fase del workflow.
|
||||
|
||||
Il lavoro è diviso in due progetti autonomi:
|
||||
|
||||
- [Memory management](2026-09-08-memory-management.md);
|
||||
- [Evidence management](2026-09-08-evidence-management.md).
|
||||
|
||||
I progetti condividono l'esperienza di gestione e i componenti appropriati, mantenendo
|
||||
distinti i contenuti, le regole di validazione e i percorsi di persistenza.
|
||||
|
||||
### Collocazione dei due accessi
|
||||
|
||||
L'ordine previsto nell'accordion Administration è:
|
||||
|
||||
```text
|
||||
Administration
|
||||
Database management
|
||||
Memory management
|
||||
Evidence management
|
||||
────────────────────
|
||||
Workspace management
|
||||
Pi management
|
||||
```
|
||||
|
||||
Memory management ed Evidence management sono due voci autonome, allo stesso livello
|
||||
di Database management. «Sotto» indica soltanto la posizione fisica nella navigazione.
|
||||
Non sono sottopagine, tab o funzionalità di Database management. Ciascuna apre la
|
||||
propria pagina e possiede il proprio stato di navigazione.
|
||||
|
||||
### Decisioni già acquisite sulla Memory
|
||||
|
||||
- La Memory serve a migliorare schema linking e generazione SQL di domande future.
|
||||
- Il perimetro comprende chiarimenti di dominio riutilizzabili, regole corrette per
|
||||
join, filtri e aggregazioni, domande risolte consultabili ed errori da evitare
|
||||
quando il motivo è stato compreso e approvato. Le scelte occasionali non diventano
|
||||
regole generali; possono restare nel contesto di un exemplar.
|
||||
- Il formato della memory card è allineato per analogia a quello delle Evidence;
|
||||
origine e dominio restano separati. Le Memory non entrano nel canone Evidence.
|
||||
- La gestione avviene tramite CRUD e form interni a ThothII.
|
||||
- L'evoluzione del modulo Memory è interna a ThothII, riusando l'infrastruttura
|
||||
dell'installazione e senza adottare un framework esterno per governarne il comportamento.
|
||||
- Il progetto comprende ricerca semantica e lessicale ibrida in Qdrant, filtri
|
||||
sull'ambito e collegamenti espliciti fra card percorsi dal core. Non introduce
|
||||
un database a grafi dedicato e non rinvia il grafo a una successiva sperimentazione.
|
||||
- PostgreSQL, già presente nell'installazione, è l'archivio autorevole di card,
|
||||
collegamenti e dipendenze, in tabelle proprie del modulo Memory. Sostituisce il
|
||||
registro JSONL; Qdrant è una proiezione rigenerabile, con sincronizzazione esplicita.
|
||||
- I collegamenti sono proposti e approvati insieme alle card nel riepilogo finale
|
||||
e gestibili manualmente da Administration. Cancellare una card elimina anche i
|
||||
collegamenti che la coinvolgono, conservando le altre card.
|
||||
- Gli exemplar `solved_question` usano il formato card con consumo consultativo.
|
||||
- Il core prepara durante il lavoro un riepilogo finale modificabile delle nuove
|
||||
Memory e degli aggiornamenti proposti. Il reviewer seleziona cosa salvare; la
|
||||
cancellazione resta nel CRUD amministrativo.
|
||||
- Le Memory vengono proposte nei gate pertinenti: chiarimenti all'inizio, regole di
|
||||
collegamento nello schema linking e regole di calcolo durante la costruzione SQL.
|
||||
Le approvazioni sono integrate nei gate, senza una domanda separata per ogni card.
|
||||
- Una modifica sostituisce il contenuto corrente: non è richiesta una cronologia
|
||||
aggiuntiva delle revisioni delle Memory o una ricostruibilità storica dedicata.
|
||||
- Se un riferimento allo schema rende una Memory inutilizzabile, il proprietario
|
||||
sceglie la cancellazione anziché lo stato «Needs review». Dopo una sincronizzazione
|
||||
riuscita dello schema fisico, il backend comunica gli elementi rimossi al modulo
|
||||
Memory, che cancella le card dipendenti e le proiezioni. La relazione fra card ed
|
||||
elementi dello schema deve essere strutturata; cleanup del Catalog ed errori di
|
||||
connessione non sono prove di rimozione fisica.
|
||||
- I conflitti fra Memory ed Evidence si risolvono con azioni chiuse, specifiche e
|
||||
accompagnate dal contenuto risultante. La scelta alimenta una correzione degli
|
||||
archivi attraverso i rispettivi percorsi, con stato di pubblicazione esplicito;
|
||||
è sempre possibile dichiarare inadeguate le proposte e richiederne la riformulazione.
|
||||
- La verifica usa test funzionali automatici e regressioni per casi concreti; non
|
||||
promette un miglioramento qualitativo generale o un benchmark con/senza Memory.
|
||||
- Le sessioni esistenti non vincolano il design. Il loro azzeramento durante lo
|
||||
sviluppo, se necessario, è autorizzato; non è un'operazione eseguita da questi documenti.
|
||||
|
||||
La decisione di non conservare uno storico riguarda le Memory. Non modifica
|
||||
automaticamente il contratto di authoring e pubblicazione delle Evidence.
|
||||
|
||||
### Salvataggio delle Evidence
|
||||
|
||||
In Q12 il proprietario rifiuta la separazione fra `Save draft` e `Publish`.
|
||||
La scelta successiva dell'editor esterno sostituisce il Save della form con il
|
||||
salvataggio dei file e un comando manuale di consolidamento: verifica la struttura,
|
||||
indica le correzioni necessarie e, se valido, aggiorna metadati, corpus e indice.
|
||||
Acquisisce anche aggiunte e cancellazioni. Segue il controllo del diff con commit e
|
||||
push manuali dell'operatore; non sono previsti watcher, Git automatico o un editor
|
||||
in Evidence management. La pagina mostra cartella, percorsi sull'host e comandi;
|
||||
il [piano Evidence](2026-09-08-evidence-management.md) specifica la sequenza.
|
||||
Il consolidamento attiva localmente il contenuto; un push mancante o fallito lascia
|
||||
il trasferimento al remoto da completare manualmente. L'ultimo chiarimento
|
||||
elimina il requisito di aggiornare sessioni aperte a seguito di modifiche
|
||||
amministrative: durante tali modifiche il core è fermo o la contemporaneità può
|
||||
essere ignorata. Rimangono le correzioni deliberate dalla sessione stessa.
|
||||
La review di Q11 distingue le draft dello specialista dalle Evidence raffinate
|
||||
locali; raccomanda di preservare le prime e gestire le seconde su file persistenti,
|
||||
senza PostgreSQL condiviso o scritture automatiche nel repository delle fonti.
|
||||
In Q13 è approvata
|
||||
la precedenza della correzione manuale quando una fonte aggiornata la contraddice:
|
||||
resta attiva fino alla risoluzione esplicita del confronto in Evidence management.
|
||||
Le Evidence cancellate non ricompaiono automaticamente durante la rigenerazione.
|
||||
Q14 consente di crearle senza documento esterno, in R0 tramite un nuovo Markdown: una
|
||||
dichiarazione manuale sostiene il testo corrente, con l'eventuale documento
|
||||
originario conservato come provenienza distinta. Q15 limita la riacquisizione
|
||||
delle fonti esterne a una richiesta esplicita dell'amministratore; il normale
|
||||
salvataggio e il recall usano il contenuto già acquisito.
|
||||
L'[ADR 0019](../adr/0019-author-evidence-in-app-with-automatic-activation.md) registra
|
||||
l'evoluzione del contratto, ancora da implementare.
|
||||
|
||||
## Stato verificato nel repository
|
||||
|
||||
`frontend/src/shell/AppShell.tsx` contiene Administration con Database management,
|
||||
Workspace management e Pi management. Non contiene le due pagine richieste.
|
||||
|
||||
Il modulo Memory espone già comandi CLI per elenco, dettaglio, aggiornamento,
|
||||
cancellazione e ricerca, ma manca una superficie CRUD amministrativa web.
|
||||
Il riepilogo di una sessione mostra soltanto le Memory collegate alla sessione.
|
||||
Il [contratto attuale della Memory](../gestione-memory.md) descrive registro JSONL
|
||||
canonico e indice Qdrant derivato.
|
||||
|
||||
Le Evidence hanno già un percorso di consultazione e modifica dei documenti nel
|
||||
repository di authoring, descritto in [Evidence: sources, preparation, and review](../evidence.md).
|
||||
Manca una pagina amministrativa per queste operazioni dentro ThothII. Il contratto
|
||||
attuale prevede che ThothII legga e pubblichi il repository, senza modificarlo,
|
||||
creare commit o eseguire push: l'editing amministrativo richiede evolvere questo
|
||||
confine, come esplicitato nel progetto Evidence.
|
||||
|
||||
## Esperienza comune
|
||||
|
||||
L'amministratore lavora nell'interfaccia operativa esistente, con una lista densa
|
||||
e leggibile e un'area di dettaglio. Si riusano tema, controlli, focus e navigazione
|
||||
già definiti in PRODUCT.md e DESIGN.md.
|
||||
|
||||
- Selettore di workspace, ricerca testuale, filtri combinabili, ordinamento e paginazione.
|
||||
- Elenco completo dei record persistiti, indipendente dalla disponibilità della
|
||||
ricerca semantica. Una ricerca per similarità può affiancarlo, senza limitarlo ai
|
||||
pochi risultati del recall del core.
|
||||
- Apertura del contenuto completo, dell'ambito di applicazione e della provenienza.
|
||||
- Creazione e modifica Memory mediante form; per Evidence R0, percorsi ed esempi
|
||||
Markdown per editor esterni, consolidamento e seguito Git manuali.
|
||||
- Cancellazione con indicazione precisa dell'oggetto e del suo effetto; per Evidence
|
||||
R0 la rimozione del file è acquisita dal consolidamento.
|
||||
- Stato esplicito di salvataggio e disponibilità per il core, con recupero dagli errori.
|
||||
- Filtri e posizione nell'elenco conservati quando si apre e si chiude un record.
|
||||
- Controlli utilizzabili da tastiera; stato vuoto, nessun risultato e indisponibilità
|
||||
del servizio distinguibili. Chrome in inglese, contenuti nella lingua del workspace.
|
||||
|
||||
Le due pagine non dipendono dalla selezione di un database in Database management.
|
||||
Eventuali filtri su tabelle e colonne usano riferimenti al catalogo quando disponibili;
|
||||
la loro assenza non impedisce di consultare i contenuti registrati.
|
||||
|
||||
Componenti condivisibili: barra di ricerca e filtri, lista, paginazione, struttura
|
||||
del dettaglio, campi comuni della card, provenienza e feedback delle operazioni.
|
||||
Form Memory, istruzioni di manutenzione Evidence, autorizzazione, validazione, pubblicazione e
|
||||
persistenza rimangono responsabilità dei rispettivi moduli. Il riuso del frontend
|
||||
non introduce un archivio canonico unico per Memory ed Evidence.
|
||||
|
||||
## Confini e integrazione
|
||||
|
||||
Entrambe le pagine appartengono ad Administration e devono applicare il controllo
|
||||
amministrativo anche nelle API. La collocazione visiva non assegna automaticamente
|
||||
le autorizzazioni di Database management ai nuovi moduli.
|
||||
|
||||
Il progetto Memory può essere consegnato senza attendere il progetto Evidence.
|
||||
I componenti comuni si estraggono quando servono ai flussi reali di entrambi.
|
||||
La verifica finale congiunta copre ordine della navigazione, accesso indipendente,
|
||||
filtri, percorsi di manutenzione e feedback coerenti, isolamento fra workspace e assenza di effetti
|
||||
incrociati fra i due domini.
|
||||
|
||||
La separazione fra Reference Vector Collection e Memory Vector Collection rimane
|
||||
quella dell'[ADR 0017](../adr/0017-separate-reference-vectors-from-runtime-memory.md).
|
||||
Un'operazione amministrativa sulle Evidence non cancella le Memory; una cancellazione
|
||||
di Memory non elimina Evidence, Schema o metadati del database.
|
||||
|
||||
## Piano esecutivo dei due progetti
|
||||
|
||||
Il riesame mantiene i requisiti funzionali Q1–Q15 e semplifica le scelte tecniche
|
||||
secondo le condizioni descritte sopra. L'ordine di lavoro parte dalla Memory e
|
||||
riusa poi i componenti effettivamente comuni per Evidence management. Le API e
|
||||
il coordinamento delle scritture attuano questi vincoli; la distinzione fra draft
|
||||
esterne e archivio locale sostituisce l'ipotesi di un unico archivio Git da modificare.
|
||||
|
||||
| Ordine | Incremento | Risultato verificabile | Dipendenze |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | M1 — Archivio e CRUD Memory | PostgreSQL autorevole, API e pagina con elenco completo, filtri, form e cancellazione; collegamenti e dipendenze persistiti, proiezioni aggiornate o invalidate | Nessuna dipendenza dal progetto Evidence |
|
||||
| 2 | M2 — Ricerca Memory | Ricerca ibrida con filtri ed espansione limitata dei collegamenti; risultati coerenti con il contenuto corrente | M1 |
|
||||
| 3 | M3 — Memory nel workflow | Riepilogo finale, uso delle categorie nei gate e cancellazione dopo sincronizzazione fisica riuscita | M1 e M2 |
|
||||
| 4 | E1 — Preparazione e archivio Evidence | Draft esterne, raffinamento del sistema, file canonici locali persistenti e protezione delle correzioni/cancellazioni | Q11–Q15 riesaminate; non richiede il runtime Memory |
|
||||
| 5 | E2 — Manutenzione e consolidamento Evidence | Pagina con percorsi dei Markdown; comando manuale di verifica e attivazione; istruzioni per diff, commit e push | E1 |
|
||||
| 6 | E3 — Fonti e conflitti di aggiornamento | Importazione delle origini supportate, refresh esplicito, confronto con le correzioni manuali | E1 ed E2 |
|
||||
| 7 | X1 — Integrazione finale | Correzioni persistenti dei conflitti Memory/Evidence e verifica congiunta delle due pagine | M3 ed E3 |
|
||||
|
||||
E1–E3 sono un progetto separato: la sequenza è l'ordine operativo scelto per questa
|
||||
consegna, non una dipendenza tecnica dal modulo Memory. Il CRUD Memory è utilizzabile
|
||||
come primo incremento; M2 e M3 restano obbligatori nel progetto attuale. La correzione
|
||||
completa dei conflitti fra i due archivi si considera consegnata soltanto con X1.
|
||||
|
||||
### Responsabilità di implementazione
|
||||
|
||||
- Il harness possiede contratti, persistenza e operazioni dei moduli Memory ed
|
||||
Evidence. Il backend applica autorizzazioni, espone le API e orchestra le
|
||||
operazioni; non introduce una seconda implementazione delle stesse scritture.
|
||||
- Il Metadata Catalog rimane responsabilità del backend. Una sincronizzazione
|
||||
fisica riuscita chiama la pulizia Memory nello stesso flusso, con gli elementi
|
||||
effettivamente rimossi nell'ambito controllato e un recupero dopo interruzione.
|
||||
La pulizia non dipende dalla UI e non richiede un bus di eventi.
|
||||
- Le pagine condividono controlli di consultazione e feedback; logica dei kind, fonte autorevole e
|
||||
attivazione rimangono nei rispettivi moduli. L'AppShell ospita le due voci autonome
|
||||
nell'ordine concordato.
|
||||
- Le modifiche coordinate hanno gestione esplicita di errori e retry. I controlli
|
||||
sulla versione corrente impediscono sovrascritture inconsapevoli senza richiedere
|
||||
uno storico delle Memory. I retry non duplicano card o collegamenti. Il normale
|
||||
salvataggio è sequenziale, con un esito persistente da recuperare se incompleto;
|
||||
non richiede nuovi worker, code generiche o coordinamento delle sessioni aperte.
|
||||
|
||||
### Verifiche e chiusura della consegna
|
||||
|
||||
Ogni incremento esegue i test delle operazioni che cambia e i controlli dei layer
|
||||
coinvolti: pytest/ruff per il harness, vitest e typecheck per backend/frontend.
|
||||
Le pagine sono verificate anche nel browser per navigazione, filtri, form, errori
|
||||
e uso da tastiera. I contratti e i test specifici sono nei due piani di progetto.
|
||||
|
||||
X1 verifica sia i conflitti che correggono Memory sia quelli che correggono Evidence,
|
||||
inclusi utente privo dell'autorizzazione necessaria, proposta rifiutata, errore di
|
||||
attivazione e retry. Il gate deve mostrare lo stato reale dell'archivio: la sola
|
||||
risoluzione della domanda corrente non dimostra che la correzione sia persistita.
|
||||
La verifica congiunta copre inoltre isolamento dei workspace, ordine dei link e
|
||||
assenza di cancellazioni incrociate.
|
||||
|
||||
I contratti correnti vengono aggiornati insieme al relativo codice. Alla fine si
|
||||
aggiornano PROJECT_STATE.md e documentazione operativa e si esegue la build strict.
|
||||
La verifica della generazione con un modello reale rimane distinta dai test
|
||||
deterministici; non si promette un benchmark generale di miglioramento qualitativo.
|
||||
|
||||
Gli incrementi approvati sono implementati e disponibili nel Docker locale.
|
||||
I rapporti di validazione distinguono i test deterministici, i servizi reali e le
|
||||
prove con il modello configurato. Le verifiche sintetiche non modificano la
|
||||
conoscenza PSD; la valutazione dei contenuti reali rimane una decisione del reviewer.
|
||||
@@ -0,0 +1,253 @@
|
||||
# Revisione di semplicità: Memory ed Evidence
|
||||
|
||||
Data: 2026-09-08. Stato: archivio locale Markdown, editor esterni e consolidamento
|
||||
manuale con seguito Git scelti per la release 0; conseguenze esplicitate,
|
||||
restanti semplificazioni confermate, chiariti impatto core e controllo Git.
|
||||
Nessuna modifica applicativa.
|
||||
|
||||
## Condizioni che guidano la revisione
|
||||
|
||||
Chi amministra il sistema è competente e deve vedere chiaramente cosa produce ogni
|
||||
azione. Durante il CRUD amministrativo di Memory ed Evidence si può assumere che
|
||||
non ci siano attività core in corso; la loro eventuale contemporaneità non è un
|
||||
caso da supportare con meccanismi dedicati.
|
||||
|
||||
Lo specialista di contesto può essere una persona diversa da chi gestisce
|
||||
l'installazione. Scrive le draft delle Evidence senza dover accedere a PostgreSQL,
|
||||
amministrarlo o disporre della stessa installazione. Il flusso fondamentale resta:
|
||||
|
||||
1. Lo specialista scrive e consegna le draft in documenti accessibili al sistema.
|
||||
2. Il sistema le acquisisce e le raffina in Evidence strutturate.
|
||||
3. Il sistema conserva localmente le Evidence per consultazione e manutenzione.
|
||||
|
||||
La proposta avanzata durante la revisione di usare PostgreSQL come archivio
|
||||
autorevole anche delle Evidence è ritirata. Confrontava il costo del solo CRUD
|
||||
interno, senza rappresentare adeguatamente l'autonomia di chi produce le fonti.
|
||||
Un database dietro un'interfaccia non richiederebbe di per sé accesso SQL agli autori,
|
||||
né un database condiviso; questo però non risolve da solo il flusso di redazione e
|
||||
consegna esterno. Non propongo di introdurre tale dipendenza.
|
||||
|
||||
## Archivio locale delle Evidence accettato dopo il chiarimento
|
||||
|
||||
Il proprietario ha accettato i file locali e richiede una gestione facile da trovare
|
||||
e usare anche per uno specialista non tecnico. Il formato di lavoro è Markdown;
|
||||
JSONL non è una superficie di gestione delle Evidence. Il proprietario ha scelto
|
||||
editor esterni per la release 0, chiedendo di indicare chiaramente dove sono i file.
|
||||
|
||||
| Contenuto | Responsabile | Conservazione e uso |
|
||||
| --- | --- | --- |
|
||||
| Draft originali | Specialista di contesto | File o repository delle fonti, redigibili e consegnabili indipendentemente dall'installazione |
|
||||
| Evidence raffinate e correzioni locali | Sistema e persone autorizzate alla manutenzione del contenuto | File Markdown in un archivio locale persistente dell'installazione, consultabili dall'applicazione e modificabili con editor esterni |
|
||||
| Indice di ricerca | Sistema | Qdrant, ricostruibile dalle Evidence locali correnti |
|
||||
|
||||
Questa è una revisione della parte tecnica di Q11: distingue l'autorità delle draft
|
||||
esterne dall'archivio delle Evidence raffinate usate dalla singola installazione.
|
||||
Il repository delle fonti rimane utilizzabile; il consolidamento delle Evidence
|
||||
locali non esegue commit o push e non richiede un PostgreSQL condiviso. Il seguito
|
||||
manuale ora richiesto comprende controllo del diff, commit e push nel repository
|
||||
che contiene i file curati. L'archivio è una working tree persistente; draft e unità
|
||||
curate possono stare nello stesso repository, mantenendo distinta la loro funzione.
|
||||
|
||||
Le conseguenze devono essere esplicite. Una correzione locale cambia ciò che usa
|
||||
quell'installazione e non viene rispedita automaticamente allo specialista o ad
|
||||
altre installazioni. I file restano trasferibili per un passaggio esplicito; non
|
||||
si costruisce una sincronizzazione bidirezionale. L'archivio locale va conservato
|
||||
e incluso nelle copie di sicurezza: dopo una correzione non è più un semplice
|
||||
output eliminabile e rigenerabile dalle draft senza perdita di lavoro.
|
||||
|
||||
Memory mantiene PostgreSQL locale come archivio già concordato. Le due pagine
|
||||
restano separate e riusano controlli comuni; la scelta della persistenza segue il
|
||||
flusso di produzione dei rispettivi contenuti.
|
||||
|
||||
## Gestione della release 0: editor esterni scelti
|
||||
|
||||
Il proprietario sceglie il proprio editor sul Mac o PC, oppure vim, nano o
|
||||
equivalenti sul server. La proposta di editor applicativo è ritirata; non si
|
||||
integra una libreria di editing né si sviluppano form di contenuto Evidence.
|
||||
|
||||
`Evidence management` conserva lista, ricerca, filtri e dettaglio. Mostra la cartella
|
||||
del workspace e il percorso assoluto di ogni file, copiabile e risolto dalla
|
||||
configurazione effettiva. Indica l'host su cui si trova; con Docker mostra il percorso
|
||||
persistente accessibile sull'host. Le istruzioni distinguono draft originali e
|
||||
Evidence raffinate da manutenere e includono un esempio Markdown per crearne una.
|
||||
|
||||
Si modificano direttamente i file nell'archivio locale dell'installazione. Chi
|
||||
lavora su una copia sul proprio computer la riporta lì con i propri strumenti.
|
||||
Non sono richiesti upload/download web, nuove cartelle condivise o sincronizzazione.
|
||||
|
||||
Dopo aver salvato, aggiunto o rimosso file, l'operatore controlla lo stato Git,
|
||||
poi esegue un comando manuale di
|
||||
consolidamento: controlla la struttura attesa, segnala file e correzioni necessarie
|
||||
e, solo se i controlli passano, aggiorna metadati, corpus e indice. Il comando è
|
||||
rieseguibile dopo correzioni o errori tecnici. Seguono commit e
|
||||
push manuali, con le istruzioni della pagina e della documentazione operativa.
|
||||
Il core consulta solo l'ultimo corpus consolidato valido; i file in lavorazione
|
||||
e gli aggiornamenti falliti non devono introdurre contenuto parziale nella ricerca.
|
||||
La richiesta più recente sostituisce la proposta intermedia del pulsante
|
||||
`Apply file changes`; non servono un'esecuzione dalla UI, watcher o operazioni Git
|
||||
automatiche. Il salvataggio nell'editor da solo non aggiorna il recall. Il controllo
|
||||
dei file usa `git status --short` nel terminale; il normale `git diff` è disponibile
|
||||
per approfondire le righe cambiate, senza visualizzatore web o doppia revisione
|
||||
obbligatoria. Il comando riporta un breve riepilogo testuale delle modifiche.
|
||||
|
||||
Il Markdown locale deve essere realmente editabile: il testo visibile è autorevole,
|
||||
i campi richiesti sono documentati e i metadati derivati sono gestiti dal sistema.
|
||||
Il formato v3 attuale, che verifica il rendering contro una copia codificata del
|
||||
testo, va quindi adattato. Non basta indicare i percorsi dei file attuali e non si
|
||||
introduce un secondo archivio di scambio da sincronizzare. Questo comporta una
|
||||
modifica effettiva dei componenti core Evidence: parser, renderer, preparazione,
|
||||
validazione, normalizzazione e collegamento a indicizzazione/recall. E1 comprende
|
||||
nuova versione del contratto, conversione dei file esistenti e verifica del percorso
|
||||
completo; il formato interno tipizzato viene conservato dove possibile.
|
||||
|
||||
Creazione, modifica e cancellazione delle unità raffinate passano dai file e dallo
|
||||
stesso consolidamento. Un errore di accesso all'archivio non è una prova di
|
||||
cancellazione. Le correzioni approvate dal core continuano a chiamare direttamente
|
||||
il servizio di scrittura. Il proprietario ha confermato le restanti semplificazioni
|
||||
chiedendo di esplicitare impatto core e semplicità del controllo Git.
|
||||
Il [piano Evidence](2026-09-08-evidence-management.md#consolidamento-manuale-e-seguito-git--release-0)
|
||||
specifica controlli, comando previsto e sequenza Git. Dopo il consolidamento il
|
||||
contenuto è disponibile localmente; finché commit/push non sono completati, non è
|
||||
versionato/trasferito al remoto. Il sistema si affida alla disciplina dell'operatore
|
||||
e non tenta di completare o riparare automaticamente la sequenza Git.
|
||||
|
||||
## Conseguenze rispetto al piano precedente alla revisione
|
||||
|
||||
Il confronto riguarda il piano concordato prima del riesame: form strutturate per
|
||||
le unità, repository Git autorevole con scritture applicative e supporto alle
|
||||
modifiche amministrative durante sessioni aperte. Le funzionalità non erano ancora
|
||||
implementate: si confrontano due progetti, non una regressione già introdotta.
|
||||
|
||||
| Aspetto | Cosa cambia | Conseguenza pratica |
|
||||
| --- | --- | --- |
|
||||
| Gestione R0 delle Evidence | Editor esterno scelto al posto di editor e form nell'applicazione | Si usano strumenti già disponibili. La pagina indica i file; servono un Markdown realmente editabile, esempi e validazione in acquisizione. Si rinuncia alla guida e ai controlli durante la digitazione. |
|
||||
| Applicazione delle modifiche esterne | Salvare i file nell'archivio ed eseguire il consolidamento manuale | Una copia sul Mac o PC va riportata nell'archivio con gli strumenti dell'operatore. Fino al consolidamento riuscito la modifica non è disponibile al core. Gli errori strutturali indicano il seguito necessario. Non si sviluppano trasferimenti file web o watcher. |
|
||||
| Autorità delle Evidence raffinate | Archivio locale, distinto dalle draft esterne | Una correzione agisce su quell'installazione. Lo specialista che lavora alle draft e altre installazioni non la ricevono automaticamente. |
|
||||
| Cronologia e distribuzione Git | Controllo del diff, commit e push manuali dopo il consolidamento | Git conserva e trasferisce quanto l'operatore committa e pubblica. La sequenza non è imposta né completata dal sistema: se il push manca o fallisce, il core locale può già usare modifiche non trasferite. Non c'è rollback applicativo o gestione automatica dei conflitti Git. |
|
||||
| Ripristino dei dati | Le Evidence locali curate sono dati primari | Il backup deve comprenderle. Ricostruire tutto dalle sole draft recupererebbe la base, ma potrebbe perdere correzioni e cancellazioni locali; Clear deve preservare l'archivio. |
|
||||
| Attività core contemporanee | Non vengono più gestite le modifiche amministrative durante il lavoro core | Se avvengono comunque, non è garantita la coerenza della sessione in corso. Non si aggiornano contesti o SQL già prodotti. Le successive elaborazioni usano il contenuto aggiornato dopo il completamento dell'operazione. |
|
||||
| Salvataggio e indice | Operazione sequenziale con recupero minimo persistente | L'utente attende l'esito dell'indicizzazione. Un problema può richiedere Retry; il contenuto già salvato viene conservato e un esito incompleto non viene presentato come pieno successo. Il piano precedente già prevedeva questi esiti, non garantiva retry automatici. |
|
||||
| Pulizia Memory dopo sync | Chiamata diretta nel flusso esistente | Stesso effetto funzionale, con meno coordinamento interno. Rimangono il recupero dopo interruzione, i limiti dell'ambito controllato e l'esclusione di errori di connessione o cleanup del solo Catalog. |
|
||||
| Verifica semantica | Nessuna nuova valutazione generale o revisione obbligatoria a ogni Save | La responsabilità del significato resta allo specialista; i test verificano contratti e casi mirati. La validazione strutturale non garantiva la correttezza del dominio neppure nel piano precedente. |
|
||||
|
||||
Sono invariati il riepilogo Memory, le categorie ammesse, i gate esistenti, la
|
||||
ricerca ibrida e i collegamenti, le correzioni persistenti dei conflitti e la
|
||||
protezione delle modifiche manuali. Le fonti vengono aggiornate su richiesta come
|
||||
già concordato. Le scritture deliberate dal core stesso restano supportate tramite
|
||||
lo stesso servizio: l'assenza di amministrazione concomitante non le elimina.
|
||||
|
||||
Non è prevista una rinuncia alle capacità di ricerca o al contenuto delle Evidence.
|
||||
Conservare gli stessi contenuti tipizzati, ambiti e indicizzazione evita una perdita
|
||||
di qualità dovuta a un taglio di funzionalità, ma l'equivalenza del nuovo percorso
|
||||
deve essere verificata. Il formato Markdown e un editor più semplice non sono,
|
||||
da soli, una garanzia di qualità o di assenza di errori.
|
||||
|
||||
## Riesame di tutte le decisioni Q1–Q15
|
||||
|
||||
| Decisione | Esito della revisione | Approccio più semplice e conseguenza |
|
||||
| --- | --- | --- |
|
||||
| Q1 — Riepilogo Memory | Mantengo | Un riepilogo finale editabile, con selezione di cosa salvare. Nessuna approvazione ripetuta per ogni card durante la sessione. |
|
||||
| Q2 — Aggiunte e aggiornamenti | Mantengo | Mostrare contenuto risultante e record sostituito. La somiglianza non avvia fusioni automatiche; la cancellazione semantica resta esplicita nel CRUD. |
|
||||
| Q3 — Consumo nei gate | Mantengo | Usare i gate già previsti. Nessun nuovo percorso di approvazione per la sola consultazione di una Memory; exemplar consultativi. |
|
||||
| Q4 — Conflitti Memory/Evidence | Semplifico l'esecuzione | La scelta mostra quale archivio cambia e con quale testo. Chiamare lo stesso servizio di salvataggio del CRUD, con un esito unico; niente secondo sistema di pubblicazione. Le correzioni deliberate dal core restano un caso da supportare. |
|
||||
| Q5 — Dipendenze fisiche eliminate | Mantengo, con chiamata diretta | Alla fine della sincronizzazione fisica riuscita, chiamare la pulizia Memory nello stesso flusso. Mostrare le conseguenze nella conferma della sincronizzazione già esistente e il conteggio finale. Non introdurre bus di eventi o un nuovo controllo continuo del DWH. |
|
||||
| Q6 — Verifiche | Mantengo il perimetro limitato | CRUD, filtri, persistenza, cancellazioni, recupero dall'errore e casi mirati di ricerca. Nessuna valutazione qualitativa generale a ogni salvataggio, nessun secondo modello giudice obbligatorio. |
|
||||
| Q7 — Evoluzione interna | Mantengo | Riutilizzare componenti e servizi dell'installazione. Nessun framework esterno o ulteriore servizio per governare Memory. |
|
||||
| Q8 — Ibrido e collegamenti | Mantengo entrambe le capacità | Riutilizzare la ricerca ibrida; collegamenti in una lista modificabile ed espansione limitata nel core. Nessun database a grafi, editor visuale di grafi o deduzione automatica di una rete di relazioni. Le capacità restano nel progetto attuale. |
|
||||
| Q9 — PostgreSQL per Memory | Mantengo | Il database è già locale all'installazione; card, collegamenti e dipendenze restano coordinati. Qdrant è ricostruibile. Il flusso Memory non richiede un autore esterno indipendente. |
|
||||
| Q10 — Cura dei collegamenti | Mantengo | Gestirli nello stesso riepilogo e dettaglio della card. Cancellare una card elimina i collegamenti incidenti e conserva le altre card. |
|
||||
| Q11 — Archivio Evidence | Rivedo la soluzione tecnica | Draft esterne indipendenti e Evidence raffinate in file locali persistenti. Togliere commit/push dal CRUD. La modifica locale non aggiorna automaticamente la fonte dello specialista. La proposta PostgreSQL autorevole per Evidence è ritirata. |
|
||||
| Q12 — Save e sessioni aperte | Adatto agli editor esterni | Dopo il salvataggio dei file, un comando manuale consolida e attiva le modifiche; l'operatore completa poi commit/push. Nessun workflow editoriale aggiuntivo, watcher, aggiornamento delle sessioni aperte o modalità manutenzione. |
|
||||
| Q13 — Fonte cambiata e cura manuale | Mantengo, con confronto semplice | La correzione manuale prevale finché una persona decide altrimenti. Un cambiamento della fonte collegata rende disponibile il confronto; non serve dimostrare automaticamente una contraddizione semantica. Le cancellazioni non vengono annullate dalla rigenerazione. |
|
||||
| Q14 — Creazione manuale | Mantengo tramite file | Un nuovo Markdown secondo l'esempio documentato consente una Evidence manuale con provenienza dichiarata e senza documento esterno obbligatorio. Il flusso principale draft dello specialista → raffinamento locale rimane disponibile e indipendente. |
|
||||
| Q15 — Refresh delle fonti | Mantengo | Acquisizione e raffinamento delle fonti aggiornate su richiesta esplicita. Consolidamento e recall usano il contenuto locale; non cercano nuove versioni remote. |
|
||||
|
||||
Restano confermati due link autonomi sotto Database management, CRUD completo con
|
||||
filtri, assenza di storico aggiuntivo delle Memory e assenza di vincoli sulle
|
||||
sessioni di sviluppo già esistenti.
|
||||
|
||||
## Riduzioni trasversali del piano
|
||||
|
||||
**Un'operazione alla volta, con esito comprensibile.** Save per Memory e
|
||||
consolidamento manuale per Evidence validano e aggiornano l'indice in sequenza.
|
||||
L'interfaccia mostra operazione in corso,
|
||||
completata oppure errore con azione di recupero. Non espone un workflow editoriale
|
||||
di stati `draft`, `approved`, `published` per il normale CRUD. La draft dello
|
||||
specialista è il documento di ingresso della preparazione, non un secondo pulsante
|
||||
di salvataggio dell'editor delle unità locali.
|
||||
|
||||
**Recupero minimo dopo errore.** Se l'archivio è stato aggiornato ma Qdrant no, va
|
||||
detto e deve essere possibile riprovare, per Evidence rieseguendo il comando.
|
||||
Serve un'indicazione persistente del lavoro
|
||||
incompleto, sufficiente anche per ripulire una card già cancellata dopo un riavvio.
|
||||
La ricerca non deve usare contenuti rimossi o superati alla domanda successiva.
|
||||
Il piano non imponeva già una outbox o nuovi worker: la revisione rende esplicito
|
||||
che non sono richiesti né code generiche né sincronizzazioni continue.
|
||||
|
||||
**Pulizia schema diretta e ripetibile.** Il flusso esistente del Catalog può
|
||||
richiamare Memory dopo l'applicazione dello schema. Occorre coprire il crash fra
|
||||
le due scritture: conservare la pulizia pendente sul run oppure verificare di nuovo
|
||||
le dipendenze contro lo snapshot fisico riuscito e il suo ambito. Ricalcolare solo
|
||||
il nuovo diff perderebbe le rimozioni già applicate. La rimozione manuale di
|
||||
metadati Catalog o un errore di connessione non autorizzano a cancellare Memory.
|
||||
|
||||
**Nessuna gestione delle sessioni amministrate contemporaneamente.** Non progettare
|
||||
aggiornamenti a caldo, ripristino dei contesti già letti, invalidazione dello SQL,
|
||||
notifiche alle sessioni o generazioni aggiuntive per lettori paralleli. Rimangono le
|
||||
scritture esplicitamente richieste dalla sessione stessa: il riepilogo Memory e una
|
||||
correzione Evidence approvata chiamano il medesimo servizio e ne gestiscono l'esito
|
||||
prima di proseguire. Questo caso non richiede coordinare tutte le altre sessioni.
|
||||
|
||||
**Pagine essenziali.** Ricerca testuale, filtri e lista completa permettono di trovare
|
||||
i contenuti; la ricerca semantica appartiene anzitutto al core. Memory conserva le
|
||||
form; Evidence espone dettaglio, percorsi e istruzioni per la modifica esterna.
|
||||
Hash e manifest restano gestiti dal sistema. Si riusano i controlli di accesso
|
||||
esistenti; chi modifica i file necessita dei permessi sul relativo filesystem,
|
||||
senza accesso a PostgreSQL o un nuovo sistema generale di ruoli.
|
||||
|
||||
## Conseguenze delle azioni da rendere visibili
|
||||
|
||||
| Azione | Conseguenza da comunicare |
|
||||
| --- | --- |
|
||||
| Save riuscito | Il contenuto corrente è conservato ed è disponibile per le successive elaborazioni. |
|
||||
| Save con errore dell'indice | Il contenuto è conservato; la disponibilità alla ricerca non è completata. Retry completa il lavoro senza richiedere di riscrivere la modifica. |
|
||||
| Salvataggio nell'editor esterno | Cambia il file, ma non aggiorna il recall. Una copia esterna va prima riportata nell'archivio dell'installazione. |
|
||||
| Consolidamento Evidence | Acquisisce aggiunte, modifiche e cancellazioni locali; verifica la struttura e, se valida, aggiorna metadati e indice. Un errore indica cosa correggere; si riesegue il comando dopo la correzione o un errore tecnico. |
|
||||
| Commit e push manuali | Versionano e trasferiscono al repository remoto i file consolidati. Un errore Git si risolve manualmente; il consolidamento locale già riuscito non viene annullato. |
|
||||
| Delete di una Memory | La card e i collegamenti che la coinvolgono vengono rimossi; le altre card restano. |
|
||||
| Delete di una Evidence | L'unità locale non viene più usata né ricreata automaticamente; la draft originale e le altre unità derivate restano. |
|
||||
| Refresh sources | Si acquisiscono nuove versioni delle fonti e si preparano le Evidence interessate; le correzioni locali protette non vengono sovrascritte. |
|
||||
| Sincronizzazione fisica | Le Memory dipendenti da elementi effettivamente eliminati vengono cancellate; l'ambito e il conteggio dell'effetto sono visibili. |
|
||||
| Preprocessing Clear | Si eliminano i dati derivati previsti dal comando; le Evidence canoniche locali e le Memory rimangono. |
|
||||
|
||||
Non sono necessarie conferme ripetute su Save. Per le cancellazioni si usa una
|
||||
conferma concreta sull'oggetto e sulle conseguenze, integrando gli effetti nella
|
||||
conferma già presente quando l'azione è una sincronizzazione distruttiva.
|
||||
|
||||
## Cosa va comunque implementato
|
||||
|
||||
Il raffinamento locale e la scrittura di Markdown canonico/manifest esistono in
|
||||
`harness/tht/evidence/authoring.py`. Preparano e validano gli output prima della
|
||||
sostituzione con staging e rollback; non eseguono commit/push. Va separato il
|
||||
requisito di Git worktree dalla preparazione del contenuto e va integrata
|
||||
l'acquisizione delle draft esterne.
|
||||
|
||||
La materializzazione corrente in `backend/src/workspaces/evidence/materialization.ts`
|
||||
è invece ricostruita da una revisione Git: non è già l'archivio locale scrivibile
|
||||
proposto. Il renderer e il preprocessing devono consumare il nuovo archivio
|
||||
persistente. Una modifica locale non deve richiedere un nuovo commit della fonte.
|
||||
|
||||
Si riusa l'attivazione Evidence esistente dove serve a verificare un candidato e
|
||||
a recuperare da errori; l'assenza di lettori contemporanei non rende atomici file
|
||||
e Qdrant. La mutazione resta circoscritta alle Evidence e preserva Schema, relazioni,
|
||||
LSH e Memory. Il suo successo non cancella blocchi di readiness del Catalog.
|
||||
|
||||
Le verifiche prioritarie coprono il percorso draft → raffinamento → elenco/CRUD
|
||||
locale → ricerca, persistenza dopo riavvio, retry dopo errore, mancata ricomparsa
|
||||
delle unità eliminate, refresh con correzioni locali, isolamento dei workspace e
|
||||
conservazione dell'archivio locale dopo Clear. Le prove di aggiornamento live da
|
||||
amministrazione vengono eliminate; resta la verifica delle correzioni deliberate
|
||||
dal core stesso.
|
||||
|
||||
L'ordine resta Memory, Evidence e integrazione finale. I dettagli degli incrementi
|
||||
nei due piani sono lavoro interno; per l'utente rimangono due gestioni autonome.
|
||||
@@ -0,0 +1,343 @@
|
||||
# M1 — Archivio autorevole e amministrazione delle Memory Card
|
||||
|
||||
Data: 2026-09-08. Stato: M1 implementato e verificato localmente;
|
||||
confini di test confermati dal proprietario il 2026-09-08.
|
||||
|
||||
Primo incremento del progetto Memory management. Attua le decisioni già approvate
|
||||
nel piano del 2026-09-08 e nell'ADR 0018. Le scelte tecniche di dettaglio qui
|
||||
proposte derivano dalla ricognizione del runtime. Gli esiti dell'implementazione
|
||||
sono riportati nel [rapporto di verifica](2026-09-08-memory-m1-validation.md).
|
||||
|
||||
## Problem Statement
|
||||
|
||||
L'amministratore deve poter trovare, leggere e curare tutta la conoscenza
|
||||
riutilizzabile di un workspace: chiarimenti di dominio, regole SQL, domande
|
||||
risolte ed errori compresi da evitare. Oggi manca una pagina amministrativa
|
||||
dedicata e l'archivio è frammentato: le Memory sono registrate in JSONL, mentre
|
||||
gli exemplar delle domande risolte sono indicizzati attraverso un percorso distinto.
|
||||
|
||||
Questa situazione non offre un unico archivio completo di card, collegamenti e
|
||||
dipendenze strutturate. La disponibilità dell'indice non deve determinare se una
|
||||
card è consultabile o modificabile. Una modifica o cancellazione deve inoltre
|
||||
impedire che una ricerca successiva utilizzi contenuti superati, anche se
|
||||
l'aggiornamento dell'indice fallisce.
|
||||
|
||||
## Solution
|
||||
|
||||
Consegnare la pagina **Memory management** in Administration e un archivio
|
||||
PostgreSQL autorevole, appartenente al modulo Memory. La pagina consente elenco
|
||||
completo, ricerca testuale, filtri, dettaglio, creazione, modifica, cancellazione
|
||||
e gestione dei collegamenti. I contenuti restano consultabili con embedding o
|
||||
Qdrant indisponibili, purché PostgreSQL sia disponibile.
|
||||
|
||||
Un salvataggio aggiorna insieme card, collegamenti e dipendenze, poi propaga la
|
||||
modifica a Qdrant. L'amministratore vede se il contenuto è stato salvato e se è
|
||||
disponibile al recall. Se la propagazione fallisce può riprovarla, anche dopo un
|
||||
riavvio. I contenuti rimossi o superati non sono utilizzati dal recall.
|
||||
|
||||
M1 consegna l'amministrazione e la coerenza dell'archivio. La ricerca ibrida con
|
||||
espansione dei collegamenti e il nuovo riepilogo del workflow sono gli incrementi
|
||||
M2 e M3, entrambi ancora obbligatori per completare il progetto Memory.
|
||||
|
||||
## User Stories
|
||||
|
||||
1. Come amministratore, voglio aprire Memory management da Administration, così
|
||||
da curare la conoscenza senza avviare una sessione.
|
||||
2. Come amministratore, voglio scegliere esplicitamente il workspace da
|
||||
amministrare, così da sapere a quale archivio appartiene ogni operazione.
|
||||
3. Come amministratore, voglio elencare tutte le card del workspace, così da
|
||||
raggiungere anche quelle che non compaiono nel recall semantico.
|
||||
4. Come amministratore, voglio cercare per testo o identificatore e ordinare i
|
||||
risultati, così da trovare una card senza conoscerne la formulazione esatta.
|
||||
5. Come amministratore, voglio combinare filtri per famiglia, concetti, riferimenti
|
||||
a tabelle o colonne, provenienza e aggiornamento, così da restringere l'intero
|
||||
archivio prima della paginazione.
|
||||
6. Come amministratore, voglio leggere contenuto completo, ambito, motivazione e
|
||||
provenienza disponibile, così da capire quando una card è applicabile.
|
||||
7. Come amministratore, voglio creare una card manuale senza inventare una sessione
|
||||
o una decisione di origine, così da registrare conoscenza curata direttamente.
|
||||
8. Come amministratore, voglio rappresentare chiarimenti, regole SQL, domande
|
||||
risolte ed errori compresi, così da conservare i contenuti concordati.
|
||||
9. Come amministratore, voglio conservare domanda, SQL e contesto di un exemplar,
|
||||
così da distinguerlo da una regola generale.
|
||||
10. Come amministratore, voglio associare dipendenze esplicite a database, tabelle
|
||||
e colonne, così da non affidare l'identificazione degli oggetti al testo libero.
|
||||
11. Come amministratore, voglio correggere i campi consentiti dalla famiglia e
|
||||
annullare una modifica non salvata, così da controllare il contenuto corrente.
|
||||
12. Come amministratore, voglio ricevere errori di validazione comprensibili senza
|
||||
perdere il testo inserito, così da poterlo correggere.
|
||||
13. Come amministratore, voglio creare, modificare e cancellare collegamenti con
|
||||
destinazione e significato espliciti, così da curare le relazioni fra card.
|
||||
14. Come amministratore, voglio salvare card e modifiche correlate come un'unica
|
||||
operazione, così da non lasciare collegamenti o dipendenze parziali.
|
||||
15. Come amministratore, voglio cancellare una card e i suoi collegamenti
|
||||
incidenti conservando le altre card, così da rimuovere solo il contenuto scelto.
|
||||
16. Come amministratore, voglio ritrovare le modifiche dopo riapertura della pagina
|
||||
e riavvio del servizio, così da verificare che il salvataggio sia persistente.
|
||||
17. Come amministratore, voglio consultare e curare l'archivio quando embedding o
|
||||
Qdrant sono indisponibili, così da proseguire il lavoro amministrativo.
|
||||
18. Come amministratore, voglio distinguere archivio vuoto e archivio non
|
||||
disponibile, così da non interpretare un guasto come perdita dei dati.
|
||||
19. Come amministratore, voglio distinguere salvataggio fallito e contenuto
|
||||
salvato con indicizzazione incompleta, così da scegliere il recupero corretto.
|
||||
20. Come amministratore, voglio riprovare una propagazione incompleta anche dopo
|
||||
un riavvio o una cancellazione, così da completare la pulizia dell'indice.
|
||||
21. Come reviewer, voglio che una nuova ricerca escluda card eliminate o contenuti
|
||||
superati, così da ricevere soltanto conoscenza corrente.
|
||||
22. Come reviewer, voglio che gli exemplar rimangano consultativi e che una Memory
|
||||
recuperata non costituisca approvazione, così da conservare il controllo del workflow.
|
||||
23. Come amministratore, voglio che reindicizzazione e preprocessing rispettino le
|
||||
cancellazioni e le correzioni, così da non doverle ripetere.
|
||||
24. Come operatore dell'installazione, voglio preparare lo schema e configurare
|
||||
l'accesso Memory con i meccanismi esistenti, così da avviarlo senza nuovi servizi.
|
||||
25. Come proprietario del workspace, voglio che API e comandi rispettino il
|
||||
contesto autorizzato, così da evitare accessi o collegamenti fra archivi diversi.
|
||||
26. Come proprietario del workspace, voglio che il CRUD Memory lasci invariati
|
||||
Evidence e metadati del database, così da mantenere distinte le responsabilità.
|
||||
|
||||
## Implementation Decisions
|
||||
|
||||
### Responsabilità e punti d'ingresso
|
||||
|
||||
- Il modulo Memory del harness possiede modello, validazione, repository,
|
||||
mutazioni, collegamenti, dipendenze e coerenza delle proiezioni. PostgreSQL è
|
||||
autorevole; Qdrant contiene una proiezione ricostruibile.
|
||||
- I comandi Memory esistenti diventano adattatori del medesimo servizio. La
|
||||
superficie viene completata con creazione manuale, gestione dei collegamenti,
|
||||
elenco delle propagazioni incomplete e retry. Nessuna logica di persistenza
|
||||
Memory viene duplicata nel backend.
|
||||
- Il backend espone API amministrative attraverso il runner del harness,
|
||||
associando principal attendibile e configurazione del workspace alla richiesta.
|
||||
Si conservano opzioni di configurazione per comando e output JSON puro.
|
||||
- La ricognizione conferma che il harness usa già SQLAlchemy e PostgreSQL per le
|
||||
sessioni. Se ne riusano i meccanismi adatti, mantenendo separati modello,
|
||||
migrazioni e proprietà dei dati Memory. Il repository in memoria del Metadata
|
||||
Catalog è un test double del Catalog, non il modulo Memory.
|
||||
|
||||
### Modello e transazioni
|
||||
|
||||
- La card ha identità stabile, workspace, famiglia/contenuto, titolo o soggetto,
|
||||
ambito, motivazione, provenienza, concetti e date di creazione/aggiornamento.
|
||||
Le domande risolte conservano anche domanda, SQL e contesto. L'identità di una
|
||||
card manuale non dipende da una sessione né dal solo testo.
|
||||
- Il modello rappresenta le quattro categorie di contenuto approvate senza
|
||||
imporre quattro nuovi kind vettoriali o la corrispondenza con i tipi del ledger.
|
||||
Le origini manuali sono distinguibili; sessione e decisione sono riferimenti
|
||||
opzionali quando effettivamente disponibili.
|
||||
- I collegamenti sono record propri del modulo con sorgente, destinazione e
|
||||
significato. Le due card devono esistere nello stesso workspace. La cancellazione
|
||||
di una card elimina i collegamenti incidenti, senza propagarsi alle altre card.
|
||||
- Le dipendenze identificano esplicitamente database, schema, tabella e colonna
|
||||
secondo l'ambito applicabile. Il contratto consente il futuro confronto con
|
||||
lo schema fisico. Un cleanup dei metadati Catalog non deve poter cancellare
|
||||
card attraverso una cascata implicita di chiavi esterne.
|
||||
- Le tabelle logiche necessarie sono card, collegamenti, dipendenze e stato
|
||||
operativo delle proiezioni. Card e modifiche correlate si aggiornano nella
|
||||
stessa transazione. Una validazione o scrittura fallita non lascia aggiornamenti
|
||||
parziali. Non si conserva una storia delle revisioni del contenuto.
|
||||
- Le modifiche ordinarie non spostano una card in un altro workspace. Tutti gli
|
||||
identificatori ricevuti vengono verificati nel workspace dell'operazione,
|
||||
inclusi estremi dei collegamenti e riferimenti delle azioni di retry.
|
||||
|
||||
### Salvataggio, cancellazione e recall
|
||||
|
||||
- Il servizio valida l'intera mutazione, registra il nuovo stato autorevole e
|
||||
il lavoro di propagazione nella stessa transazione PostgreSQL, poi aggiorna
|
||||
Qdrant nello stesso flusso di salvataggio. Si completa un'operazione alla volta;
|
||||
non occorrono una coda generale, un worker o una sincronizzazione continua.
|
||||
- Lo stato persistente è sufficiente a distinguere la proiezione del contenuto
|
||||
corrente da una proiezione precedente e a ritentare l'azione dopo un riavvio.
|
||||
Può usare una versione tecnica o un'impronta interna; non è una cronologia
|
||||
editoriale né un ulteriore stato che l'utente debba gestire.
|
||||
- Un risultato Qdrant è utilizzabile solo se corrisponde a una card autorevole
|
||||
corrente del workspace e a una proiezione valida. Il contenuto restituito
|
||||
viene dall'archivio autorevole. La verifica si applica anche agli exemplar.
|
||||
In assenza di verifica autorevole il recall non restituisce il vecchio payload.
|
||||
- Dopo il commit PostgreSQL, una propagazione fallita lascia il contenuto
|
||||
consultabile nell'amministrazione e la sua proiezione non utilizzabile dal
|
||||
recall fino al recupero. L'esito distingue chiaramente questo caso da un
|
||||
salvataggio fallito prima del commit.
|
||||
- La cancellazione rimuove card, collegamenti incidenti e dipendenze e conserva
|
||||
soltanto i dati operativi necessari a eliminare la proiezione. La card non è
|
||||
più richiamabile anche se il punto Qdrant esiste ancora. La pulizia pendente
|
||||
resta raggiungibile dalla pagina, senza richiedere il dettaglio della card eliminata.
|
||||
- Il retry è esplicito e ripetibile. Usa lo stato corrente del repository, non
|
||||
il contenuto di una vecchia richiesta. Un retry superato non può sovrascrivere
|
||||
una correzione successiva né ricreare una card cancellata.
|
||||
- La ricostruzione degli indici Memory e solved-question usa esclusivamente
|
||||
le card autorevoli. Non reimporta automaticamente il registro JSONL, i payload
|
||||
Qdrant o le sessioni di origine. Il preprocessing delle reference mantiene
|
||||
la separazione delle collezioni stabilita nell'ADR 0017.
|
||||
- Anche i produttori attuali di Memory ed exemplar scrivono attraverso il
|
||||
servizio autorevole. Si adeguano promozione, salvataggio singolo e percorso di
|
||||
finalizzazione quanto necessario a evitare scritture dirette al solo indice.
|
||||
Un errore successivo al commit della sessione non deve annullarne la finalizzazione;
|
||||
l'esito e il recupero Memory restano espliciti. Questa transizione non introduce
|
||||
il nuovo riepilogo di approvazione previsto da M3.
|
||||
|
||||
### API, autorizzazione e configurazione
|
||||
|
||||
- Il contratto amministrativo comprende elenco, dettaglio, creazione,
|
||||
aggiornamento, cancellazione, manutenzione dei collegamenti, stato delle
|
||||
propagazioni incomplete e retry. Le mutazioni restituiscono identità interessata,
|
||||
esito del salvataggio ed esito della propagazione; gli errori non espongono segreti.
|
||||
- L'elenco restituisce pagina, conteggio totale filtrato e ordinamento stabile
|
||||
con identificatore come discriminante. Ricerca testuale e filtri combinabili
|
||||
agiscono sull'intero archivio prima della paginazione, senza embedding.
|
||||
- Il backend distingue input invalido, accesso negato, record assente nel
|
||||
workspace richiesto, archivio indisponibile e propagazione incompleta dopo
|
||||
salvataggio. Un archivio indisponibile non produce una lista vuota riuscita.
|
||||
- Si riusano autenticazione, controlli di accesso e trasmissione del principal.
|
||||
Il catalogo attuale non ha un permesso Memory dedicato: la proposta è aggiungere
|
||||
la capability amministrativa Memory al ruolo admin esistente, senza introdurre
|
||||
ruoli nuovi. Il controllo copre anche letture amministrative e retry.
|
||||
- Le operazioni amministrative e i comandi esposti non permettono bypass del
|
||||
controllo nel harness. Le scritture già previste dal workflow conservano il
|
||||
proprio contesto autorizzato di sessione; non diventano CRUD amministrativo
|
||||
liberamente accessibile a un utente ordinario. Il recall rimane accessibile
|
||||
secondo le regole del workflow.
|
||||
- M1 include configurazione della connessione al PostgreSQL dell'installazione,
|
||||
distribuzione protetta delle credenziali al harness, migrazioni versionate e
|
||||
privilegi runtime necessari alle sole tabelle Memory. Si riusano i meccanismi
|
||||
di configurazione generata, segreti e provisioning esistenti; non si usano le
|
||||
credenziali di lettura del DWH. I nomi fisici di schema, tabelle e parametri
|
||||
vengono fissati nell'implementazione rispettando questi contratti.
|
||||
- Le migrazioni sono eseguite dal percorso di preparazione dell'installazione,
|
||||
non da una richiesta HTTP ordinaria. Schema mancante o non aggiornato produce
|
||||
un errore operativo comprensibile. La transizione non prevede doppie scritture
|
||||
permanenti o conservazione del comportamento delle sessioni storiche.
|
||||
|
||||
### Pagina amministrativa
|
||||
|
||||
- Memory management è un accesso indipendente nell'Administration dell'AppShell,
|
||||
immediatamente dopo Database management, senza richiedere una sessione attiva
|
||||
o l'ingresso in Database management.
|
||||
- La pagina rende esplicito il workspace e offre lista paginata, ricerca,
|
||||
filtri, ordinamento, dettaglio completo e form. Le modifiche hanno salvataggio,
|
||||
annullamento e validazione. La cancellazione rende chiari contenuto interessato
|
||||
e rimozione dei collegamenti, seguendo le convenzioni UI esistenti.
|
||||
- Il feedback distingue operazione in corso, salvataggio fallito, contenuto
|
||||
salvato con indice incompleto e operazione completata. Il recupero delle
|
||||
cancellazioni pendenti è disponibile anche quando la card non compare più in lista.
|
||||
- I controlli sono accessibili da tastiera e hanno etichette comprensibili.
|
||||
Chrome e messaggi UI sono in inglese; il contenuto resta nella lingua del workspace.
|
||||
Hash, versioni tecniche e dettagli delle tabelle non sono esposti nel flusso ordinario.
|
||||
|
||||
## Testing Decisions
|
||||
|
||||
Confini confermati dal proprietario: usare tre confini già presenti nel
|
||||
repository, concentrando la maggior parte dei casi sul servizio pubblico Memory
|
||||
del harness. I test osservano risultati, persistenza ed errori; non vincolano
|
||||
metodi privati, numero di query o disposizione interna delle tabelle.
|
||||
|
||||
### 1. Servizio pubblico Memory e suoi comandi
|
||||
|
||||
Usare PostgreSQL reale in testcontainers, come nei test del repository delle
|
||||
sessioni, e gli adapter vettoriali sostituibili già impiegati nei test di recall
|
||||
e del ciclo di vita solved-question. Gli embedding dei casi deterministici sono
|
||||
controllati. Un gruppo mirato con Qdrant reale verifica aggiornamento, cancellazione
|
||||
e ricostruzione della proiezione; non richiede DWH remoto o un modello generativo.
|
||||
|
||||
Questo confine verifica il comportamento di archivio, propagazione e recall:
|
||||
|
||||
| Caso | Risultato osservabile richiesto |
|
||||
| --- | --- |
|
||||
| Creare e riaprire il repository | La card completa, i collegamenti e le dipendenze sono persistiti; l'origine manuale non contiene sessioni inventate. |
|
||||
| Salvare una card di ciascuna categoria | Contenuto, ambito e dati specifici sono rappresentabili e leggibili senza dipendere dai tipi del ledger. |
|
||||
| Cercare un record fuori dalla prima pagina | Filtri combinati, totale e ordinamento si riferiscono all'intero archivio. |
|
||||
| Fallire una scrittura correlata | Card, collegamenti e dipendenze mantengono tutti lo stato precedente. |
|
||||
| Indicare una card di un altro workspace | Lettura, mutazione, collegamento e retry non accedono al contenuto estraneo. |
|
||||
| Cancellare una card collegata | Scompaiono card e collegamenti incidenti; le altre card restano intatte. |
|
||||
| Rendere embedding o Qdrant indisponibili | Elenco e dettaglio funzionano; il CRUD persiste e distingue la propagazione incompleta. |
|
||||
| Fallire PostgreSQL prima del commit | Nessun falso salvataggio riuscito e nessun nuovo contenuto propagato. |
|
||||
| Fallire Qdrant dopo un aggiornamento | Il dettaglio contiene la correzione; il recall esclude il vecchio risultato. |
|
||||
| Fallire Qdrant dopo una cancellazione | La card non è richiamabile; il lavoro di pulizia resta visibile e recuperabile. |
|
||||
| Riavviare fra commit e propagazione | Il lavoro incompleto permane e un retry lo completa. |
|
||||
| Ritentare dopo un errore o un esito incerto | Non si creano duplicati; si applica lo stato corrente senza ripristinare contenuti superati. |
|
||||
| Indice con punto orfano o versione superata | Recall Memory ed exemplar lo escludono anche se ha il punteggio più alto. |
|
||||
| PostgreSQL indisponibile durante il recall | Il servizio segnala l'indisponibilità senza servire payload non verificati. |
|
||||
| Ricostruire dopo modifica o cancellazione | Il contenuto corretto è conservato; nessuna card viene ricreata dalle sessioni o da vecchi indici. |
|
||||
| Eseguire promozione o finalizzazione corrente | I nuovi contenuti passano dall'archivio; un errore Memory successivo non annulla una sessione già finalizzata. |
|
||||
| Applicare migrazioni e riavviare | Lo schema è utilizzabile con il ruolo runtime previsto; la preparazione è ripetibile e non richiede privilegi di migrazione nelle richieste ordinarie. |
|
||||
|
||||
I test CLI coprono solo l'adattamento che il servizio non prova: parsing, principal,
|
||||
workspace, esiti macchina e JSON puro. I test di integrazione riusano le convenzioni
|
||||
L0 del harness. I test di recall esistenti continuano a verificare che decisioni
|
||||
già registrate nella sessione e famiglie non ammesse non vengano riproposte.
|
||||
|
||||
### 2. API amministrative Fastify
|
||||
|
||||
Usare l'iniezione HTTP e il runner sostituibile già presenti nei test backend,
|
||||
seguendo i test delle route Catalog e dell'autorizzazione. Verificare principal
|
||||
autenticato, admin e utente ordinario; validazione; selezione del workspace;
|
||||
contratto delle risposte e mappatura degli errori. Includere letture, collegamenti
|
||||
e retry, non soltanto le mutazioni delle card.
|
||||
|
||||
Questi test provano il confine HTTP e il passaggio al harness. Non si considera
|
||||
il runner simulato una prova della transazione PostgreSQL o della coerenza Qdrant.
|
||||
La normale policy CSRF dell'applicazione resta applicata alle nuove mutazioni.
|
||||
|
||||
### 3. Pagina nell'AppShell
|
||||
|
||||
Usare React Testing Library, MSW e le convenzioni dei test di AppShell e Database
|
||||
management. Verificare ingresso amministrativo, scelta workspace, lista completa,
|
||||
filtri, dettaglio, form, annullamento, errori, collegamenti e retry dopo cancellazione.
|
||||
Controllare il comportamento tramite elementi accessibili e contenuto visibile.
|
||||
|
||||
Un percorso browser mirato sullo stack reale collega i tre confini: amministratore
|
||||
autenticato, creazione manuale, modifica, riapertura della pagina, cancellazione
|
||||
e verifica dell'assenza nel recall. I test browser con API intercettate provano
|
||||
interazione e presentazione; non vengono dichiarati prova della persistenza.
|
||||
|
||||
Non si replica l'intera matrice su tutti e tre i confini. PostgreSQL, indice e
|
||||
recupero sono verificati nel harness; autenticazione e trasporto nel backend;
|
||||
interazione e feedback nella UI. Il percorso integrato copre il collegamento reale.
|
||||
|
||||
### Verifica della consegna
|
||||
|
||||
Eseguire i test interessati e i gate documentati dei layer modificati, inclusi
|
||||
typecheck TypeScript, lint Python e build documentale strict. Le verifiche con
|
||||
PostgreSQL, Qdrant e browser reale hanno esito riportato separatamente; se un
|
||||
servizio necessario manca, il relativo gate resta aperto.
|
||||
|
||||
M1 non richiede una valutazione della qualità SQL generata da un LLM. I test
|
||||
deterministici non sono presentati come prova di tale capacità: gli eventuali
|
||||
casi reali appartengono agli incrementi che cambiano generazione e workflow.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Ricerca ibrida, nuova selezione per ambito ed espansione dei collegamenti: M2.
|
||||
- Riepilogo finale modificabile, nuove categorie nei gate e pulizia dopo una
|
||||
sincronizzazione fisica del Catalog: M3. M1 ne prepara card e dipendenze.
|
||||
- Authoring, consolidamento e manutenzione Evidence: E1–E3; risoluzione persistente
|
||||
congiunta dei conflitti fra Memory ed Evidence: X1.
|
||||
- Revisione storica delle card, snapshot per vecchie sessioni, migrazione dei dati
|
||||
di sviluppo o compatibilità con il registro JSONL come archivio operativo.
|
||||
- Aggiornamento a caldo delle altre sessioni, nuove invalidazioni dello SQL già
|
||||
generato, coordinamento generale dei lettori paralleli e modalità manutenzione.
|
||||
- Nuovi servizi PostgreSQL o graph database, code generiche, worker e polling continuo.
|
||||
- Promozione automatica di rifiuti senza spiegazione o scelte occasionali,
|
||||
consolidamento automatico e benchmark generale della qualità del modello.
|
||||
- Deploy o pulizia dell'installazione PSD: restano soggetti ai rispettivi piani e gate.
|
||||
|
||||
## Further Notes
|
||||
|
||||
Fonti: progetto **Memory management** del 2026-09-08; piano comune
|
||||
**Amministrazione di Memory ed Evidence**; **Revisione di semplicità: Memory ed
|
||||
Evidence**; glossario di dominio; ADR 0017 sulla separazione delle collezioni e
|
||||
ADR 0018 su PostgreSQL autorevole e Qdrant per il retrieval.
|
||||
|
||||
La ricognizione ha verificato MemoryRecord, recall ordinario, ricerca degli
|
||||
exemplar, comandi Memory, repository PostgreSQL delle sessioni, runner del harness,
|
||||
autorizzazione backend e navigazione amministrativa. Il recall ordinario oggi
|
||||
risolve già i risultati nel registro autorevole, mentre gli exemplar leggono
|
||||
contenuti dal payload vettoriale: M1 deve uniformare entrambe le garanzie.
|
||||
|
||||
Le scelte tecniche da fissare durante l'implementazione sono nomi e DDL delle
|
||||
tabelle, firma esatta dei nuovi comandi/API e parametri generati di connessione.
|
||||
Devono rispettare i contratti e i casi di accettazione di questa specifica;
|
||||
non riaprono le decisioni di prodotto approvate.
|
||||
|
||||
La destinazione della specifica è il tracker Gitea canonico di ThothII, con
|
||||
etichetta **ready-for-agent**. Il proprietario ha confermato i confini di test
|
||||
e autorizzato la pubblicazione il 2026-09-08. L'implementazione resta da eseguire.
|
||||
@@ -0,0 +1,103 @@
|
||||
# M1 — Implementazione e verifica
|
||||
|
||||
Data: 2026-09-08. Implementazione locale della
|
||||
[specifica approvata](2026-09-08-memory-m1-spec.md), associata all'
|
||||
[issue 27](https://git.tylconsulting.it/mptyl/ThothII/issues/27).
|
||||
|
||||
## Risultato
|
||||
|
||||
La pagina **Memory management** è disponibile nell'Administration dopo Database
|
||||
management. Gestisce le quattro famiglie di card, elenco completo, ricerca e filtri,
|
||||
ordinamento, dettaglio, creazione, modifica, cancellazione, collegamenti e dipendenze.
|
||||
Richiede un amministratore autenticato e una selezione esplicita del workspace;
|
||||
non richiede una sessione o un database DWH configurato.
|
||||
|
||||
Il harness possiede l'archivio PostgreSQL `thoth_memory`. Card, collegamenti,
|
||||
dipendenze e lavoro di propagazione sono salvati nella stessa transazione.
|
||||
La pagina distingue salvataggio fallito e contenuto salvato con indice incompleto,
|
||||
offrendo retry anche per le cancellazioni. Recall Memory ed exemplar verificano
|
||||
esistenza, workspace e proiezione corrente nell'archivio prima di restituire contenuto.
|
||||
|
||||
Promozione, salvataggio singolo e finalizzazione corrente passano dal servizio
|
||||
autorevole. Le ricevute della sorgente impediscono duplicati e ricreazione di card
|
||||
cancellate. Reindicizzazione e preprocessing non importano vecchi payload o sessioni.
|
||||
L'errore Memory non annulla una sessione già finalizzata; il gate segnala anche
|
||||
una promozione salvata con indicizzazione incompleta.
|
||||
|
||||
Le migrazioni sono versionate, controllate tramite checksum e incluse nel wheel
|
||||
e nell'immagine core. Il servizio di preparazione `catalog-migrate` le esegue dopo
|
||||
quelle del Catalog. Il runtime assume il ruolo limitato `thoth_memory_runtime`,
|
||||
con isolamento del workspace tramite RLS e senza privilegi DDL.
|
||||
|
||||
## Verifiche eseguite
|
||||
|
||||
| Confine | Esito |
|
||||
| --- | --- |
|
||||
| Harness, test senza L0/L2 | 1.134 passati; i 9 test dei percorsi portabili sono stati eseguiti separatamente e sono passati. |
|
||||
| Servizio Memory, PostgreSQL e Qdrant reali | 17 passati, inclusi CLI, migrazioni, ruolo runtime, isolamento, transazioni, outage, retry, cancellazioni, cambio famiglia e rebuild. |
|
||||
| Gate Pi | 190 passati, inclusi identità UUID e avviso dopo salvataggio con indice incompleto. |
|
||||
| Backend | 1.345 passati nella suite completa, 40 esclusi dalle condizioni previste dai test; un test di autenticazione ha superato il timeout sotto carico. Il relativo file è stato rieseguito isolato: tutti i 17 test passati. |
|
||||
| Frontend | 632 passati, inclusi ingresso dall'AppShell, form, filtri, collegamenti, dipendenze e retry delle cancellazioni. |
|
||||
| Browser integrato | Passato: autenticazione amministratore, creazione, modifica, riavvio del backend, rilettura, cancellazione e assenza nel recall. |
|
||||
| Build e tipi | Build backend e frontend, typecheck TypeScript e build documentale strict superati. |
|
||||
| Lint e diff | Ruff sui file Python modificati e `git diff --check` superati. Il lint globale segnala tre rilievi in file non modificati, elencati sotto. |
|
||||
|
||||
Il browser utilizza autenticamente frontend, login locale, Fastify, ThtRunner,
|
||||
CLI Python, PostgreSQL e Qdrant. Gli embedding sono deterministici e le attività
|
||||
Pi/sessione estranee al percorso Memory usano le fixture esistenti. Non sono state
|
||||
intercettate le API Memory. Sono stati usati container temporanei PostgreSQL 16 e
|
||||
Qdrant 1.18.2, senza accesso a un DWH remoto o a un modello generativo.
|
||||
|
||||
Il test browser ha consentito di correggere etichette accessibili instabili nei
|
||||
campi compilati e la sovrapposizione del pannello di recupero ai comandi del dettaglio.
|
||||
La selezione del workspace e l'uscita dalla pagina sono bloccate durante le operazioni.
|
||||
|
||||
Il lint globale preesistente riguarda soltanto:
|
||||
|
||||
- ordinamento import in `harness/tests/test_effective_relationships.py`;
|
||||
- ordinamento import in `harness/tests/test_p3_dwh_binding.py`;
|
||||
- uso di `datetime.UTC` in `harness/tht/mschema/catalog_snapshot.py`.
|
||||
|
||||
## Riproduzione
|
||||
|
||||
Usare Node 24 e le dipendenze installate dei tre layer. Per eseguire il harness
|
||||
in un ambiente con home non scrivibile si può impostare `THT_HOME` su una directory
|
||||
di prova. I test dei percorsi portabili devono essere eseguiti senza questo override,
|
||||
perché verificano deliberatamente la risoluzione dell'home e di `THT_DATA_ROOT`.
|
||||
|
||||
```sh
|
||||
cd harness
|
||||
THT_HOME=/private/tmp/thothii-m1-test-home .venv/bin/pytest -m 'not l0 and not l2' --ignore=tests/test_portable_paths.py -q
|
||||
.venv/bin/pytest tests/test_portable_paths.py -q
|
||||
.venv/bin/pytest tests/memory/test_administration.py -q
|
||||
npm test
|
||||
```
|
||||
|
||||
```sh
|
||||
cd backend
|
||||
npx vitest run
|
||||
npx tsc --noEmit -p .
|
||||
npm run build
|
||||
```
|
||||
|
||||
```sh
|
||||
cd frontend
|
||||
npx vitest run
|
||||
npx tsc -b
|
||||
npm run build
|
||||
THT_MEMORY_BROWSER_E2E=1 npx playwright test e2e/memory-real.spec.ts
|
||||
```
|
||||
|
||||
Il percorso browser richiede Docker, Python del harness, Go per il bridge di
|
||||
autenticazione e Chromium di Playwright. Avvia risorse isolate e le rimuove alla
|
||||
fine. Su macOS il browser deve poter avviare i processi Chromium fuori dalle
|
||||
restrizioni della sandbox. La build documentale si esegue dalla radice con
|
||||
`./scripts/build-docs.sh`.
|
||||
|
||||
## Stato della consegna
|
||||
|
||||
Le modifiche sono nel worktree locale. Nessuno stack già attivo è stato aggiornato
|
||||
e nessun dato esistente è stato migrato o eliminato. Prima di usare M1 su
|
||||
un'installazione occorrono il nuovo core e la preparazione `catalog-migrate`.
|
||||
M2 (retrieval ibrido ed espansione dei collegamenti), M3 (integrazione estesa nel
|
||||
workflow) ed Evidence management restano incrementi successivi.
|
||||
@@ -0,0 +1,342 @@
|
||||
# Progetto: Memory management
|
||||
|
||||
Data del piano: 2026-09-08. Aggiornamento 2026-09-09: M1–M3 implementati,
|
||||
con integrazione X1 per le correzioni persistenti dei conflitti. Risultati e limiti
|
||||
sono raccolti nel [rapporto X1](2026-09-09-archive-repair-x1-validation.md).
|
||||
|
||||
La [revisione di semplicità](2026-09-08-memory-evidence-simplification-review.md)
|
||||
mantiene il perimetro Memory e precisa un salvataggio sequenziale e una pulizia
|
||||
diretta dopo sincronizzazione. Non si progetta l'amministrazione contemporanea
|
||||
all'attività core.
|
||||
|
||||
Il progetto realizza il CRUD amministrativo previsto dalla discussione sull'evoluzione
|
||||
della Memory. Segue le [decisioni comuni di Administration](2026-09-08-memory-evidence-administration.md)
|
||||
e rimane distinto dal [progetto Evidence management](2026-09-08-evidence-management.md).
|
||||
|
||||
## Risultato richiesto
|
||||
|
||||
Un amministratore apre Memory management direttamente da Administration, cerca e
|
||||
filtra l'intero archivio di un workspace e gestisce le card senza avviare una sessione.
|
||||
La voce è immediatamente sotto Database management, allo stesso livello.
|
||||
|
||||
L'elenco comprende le Memory riutilizzabili e gli exemplar `solved_question`,
|
||||
distinguibili per famiglia. La modifica di un exemplar non riscrive gli artefatti
|
||||
della sessione da cui deriva e non lo trasforma in una decisione applicabile al gate.
|
||||
|
||||
## Contenuti ammessi: decisione del proprietario
|
||||
|
||||
Il perimetro concordato il 2026-09-08 comprende quattro categorie di contenuto.
|
||||
La classificazione descrive il valore della conoscenza; non impone quattro nuovi
|
||||
kind tecnici o una corrispondenza con i tipi delle decisioni del ledger.
|
||||
|
||||
| Contenuto | Cosa conserva | Esempio inventato |
|
||||
| --- | --- | --- |
|
||||
| Chiarimento di dominio | Significato riutilizzabile di un termine, con il suo ambito | «In questo workspace, ordine evaso significa che tutte le righe sono state spedite.» |
|
||||
| Regola SQL | Regola corretta per join, filtri o aggregazioni, con condizioni e motivazione | «Il codice commessa è univoco solo all'interno dell'esercizio: collegare movimenti e commesse usando codice ed esercizio.» |
|
||||
| Domanda risolta | Domanda, SQL approvato e contesto, come exemplar consultativo | «Totale degli ordini del 2024 per cliente», con la query che lo calcola. |
|
||||
| Errore da evitare | Errore compreso, motivo e comportamento corretto approvato | «Il join fra ordini e righe moltiplica il totale di testata: calcolare il totale una sola volta per ordine.» |
|
||||
|
||||
Il criterio di ammissione è l'utilità per altre domande nello stesso ambito.
|
||||
Una scelta come «questa volta usa il 2024» non è una regola riutilizzabile; il 2024
|
||||
può rimanere nel contesto della domanda risolta. Analogamente, la selezione di una
|
||||
tabella per una domanda non diventa automaticamente una regola di schema linking.
|
||||
|
||||
La categoria «errore da evitare» richiede una spiegazione verificata e approvata.
|
||||
Un timeout, una query rifiutata senza motivo o una proposta non selezionata non
|
||||
bastano a produrre conoscenza. Quando errore e correzione esprimono la stessa
|
||||
regola, una sola card conserva la regola e la sua motivazione.
|
||||
|
||||
## Formazione, aggiornamento e uso delle card
|
||||
|
||||
### Decisioni del primo round di grill-with-docs
|
||||
|
||||
Il proprietario ha approvato le tre raccomandazioni il 2026-09-08:
|
||||
|
||||
- **Q1, approvazione del salvataggio:** riepilogo finale modificabile, preparato
|
||||
durante il lavoro. Il reviewer corregge le card e sceglie quali salvare; la
|
||||
creazione manuale da Administration resta sempre disponibile.
|
||||
- **Q2, operazioni proposte dal core:** aggiunte e aggiornamenti espliciti. Il
|
||||
riepilogo distingue una nuova card dalla modifica di una card esistente e ne
|
||||
spiega il cambiamento. La sostituzione richiede la selezione del reviewer;
|
||||
la cancellazione semantica resta un'operazione del CRUD amministrativo. La pulizia
|
||||
automatica dei riferimenti invalidi è disciplinata separatamente da Q5.
|
||||
- **Q3, momento del consumo:** i chiarimenti sono proposti all'inizio, le regole di
|
||||
collegamento durante lo schema linking e le regole di calcolo durante la costruzione
|
||||
SQL. Le approvazioni entrano nei gate pertinenti, senza una domanda separata per
|
||||
ciascuna card; gli exemplar rimangono consultativi.
|
||||
|
||||
Queste sono decisioni di prodotto; i contratti runtime non sono ancora aggiornati.
|
||||
|
||||
### Decisioni del secondo round di grill-with-docs
|
||||
|
||||
Il proprietario ha approvato i chiarimenti su Q4–Q6 il 2026-09-08:
|
||||
|
||||
- **Q4, risoluzione persistente dei conflitti:** il gate propone azioni chiuse e
|
||||
specifiche per il caso, mostrando record interessati, azione e testo o ambito
|
||||
risultante. Le opzioni possono confermare l'Evidence e correggere la Memory,
|
||||
confermare la Memory e preparare una correzione dell'Evidence, oppure precisare
|
||||
gli ambiti distinti di entrambe. È sempre disponibile «Nessuna proposta è adeguata»,
|
||||
che richiede una riformulazione. Le modifiche Memory confluiscono nel riepilogo
|
||||
finale; quelle Evidence seguono l'authoring e la pubblicazione del rispettivo
|
||||
modulo. Come approvato in Q12, accettare la correzione Evidence con le autorizzazioni
|
||||
necessarie avvia anche l'attivazione automatica, senza un ulteriore `Publish`.
|
||||
Il sistema distingue proposte da approvare, aggiornamenti in corso o falliti e
|
||||
archivio già aggiornato. La sola risoluzione della domanda corrente non esaurisce il flusso.
|
||||
- **Q5, cancellazione dopo modifiche allo schema:** dopo una sincronizzazione
|
||||
riuscita dello schema fisico, il backend comunica al modulo Memory gli elementi
|
||||
rimossi. Il modulo identifica tramite dipendenze strutturate le card non più
|
||||
valide e cancella record e proiezioni ricercabili. Non si introduce lo stato
|
||||
«Needs review» per conservarle. Il controllo avviene alla sincronizzazione, senza
|
||||
scansione continua del DWH o interrogazioni aggiuntive a ogni domanda. Un cleanup
|
||||
manuale del Catalog o un errore di accesso al database non prova una rimozione
|
||||
fisica e non avvia questa pulizia. Essa è distinta dalle proposte semantiche del
|
||||
core in Q2. Oggi mancano sia i riferimenti strutturati a colonne nelle Memory sia
|
||||
il collegamento fra sincronizzazione e pulizia: devono essere implementati.
|
||||
- **Q6, verifiche concrete:** lo sviluppatore prepara ed esegue test automatici
|
||||
funzionali per CRUD, filtri, approvazioni, aggiornamenti e cancellazioni. Quando
|
||||
cambia la ricerca, verifica casi mirati con card necessarie e card fuori ambito;
|
||||
quando emerge un errore SQL riproducibile, aggiunge una regressione su dati
|
||||
controllati confrontando i risultati, senza richiedere un identico testo SQL.
|
||||
L'esperto di dominio conferma inizialmente regola e risultato atteso soltanto per
|
||||
i casi reali che lo richiedono. La verifica della generazione necessita di un
|
||||
modello reale ed è separata dalla suite deterministica: una query scritta a mano
|
||||
non prova che il modello sappia generarla. Non si introduce una valutazione umana
|
||||
permanente o un benchmark generale con percentuali di miglioramento promesse.
|
||||
|
||||
### Terzo round: direzione tecnica e capacità di ricerca
|
||||
|
||||
- **Q7, deciso:** il proprietario ha approvato l'evoluzione interna di ThothII.
|
||||
Il modulo riusa l'infrastruttura dell'installazione e integra card, CRUD, mutazioni
|
||||
e recall con i gate; non adotta un framework esterno per governare la Memory.
|
||||
- **Q8, deciso:** il proprietario ha approvato ricerca ibrida in Qdrant e collegamenti
|
||||
espliciti fra card gestiti dal core, senza un database a grafi aggiuntivo. Entrambe
|
||||
le capacità sono incluse nella pianificazione attuale; la presenza dei collegamenti
|
||||
non è rinviata alla futura comparsa di casi concreti.
|
||||
|
||||
La configurazione approvata comprende:
|
||||
|
||||
- ricerca semantica e lessicale ibrida in Qdrant, con filtri sull'ambito;
|
||||
- collegamenti espliciti fra card, proposti e revisionabili, percorsi nel core con
|
||||
espansione limitata e riordinamento dei risultati insieme a quelli della ricerca;
|
||||
- persistenza dei collegamenti coordinata con le card, con rimozione dei riferimenti
|
||||
a contenuti cancellati e rispetto dei confini fra workspace e dei gate;
|
||||
- nessun servizio di database a grafi aggiuntivo.
|
||||
|
||||
La scelta include il grafo logico, senza introdurre un servizio di graph DB.
|
||||
La qualità non è garantita dalla scelta di un motore: mantenere queste capacità
|
||||
evita una rinuncia architetturale ai collegamenti, ma non dimostra equivalenza
|
||||
qualitativa con qualsiasi soluzione basata su graph DB.
|
||||
Qdrant è il motore di ricerca; l'archivio autorevole è PostgreSQL, scelto in Q9.
|
||||
|
||||
Le [query ibride di Qdrant](https://qdrant.tech/documentation/search/hybrid-queries/)
|
||||
e i [filtri sui metadati](https://qdrant.tech/documentation/search/filtering/)
|
||||
coprono le capacità di ricerca indicate. La logica dei collegamenti di dominio
|
||||
nel core è lavoro applicativo da implementare.
|
||||
|
||||
### Decisioni del quarto round di grill-with-docs
|
||||
|
||||
- **Q9, archivio autorevole:** il proprietario ha approvato PostgreSQL, già presente
|
||||
nell'installazione, con tabelle proprie del modulo Memory per card, collegamenti
|
||||
e dipendenze dallo schema. Sostituisce il registro JSONL; Qdrant è l'indice
|
||||
rigenerabile. Le modifiche correlate vengono coordinate in PostgreSQL e la
|
||||
propagazione a Qdrant deve gestire esplicitamente errori e cancellazioni.
|
||||
- **Q10, gestione dei collegamenti:** il core propone i collegamenti insieme alle
|
||||
card, indicando destinazione e significato. Il reviewer li approva nello stesso
|
||||
riepilogo finale, senza un gate aggiuntivo. Administration ne consente creazione,
|
||||
modifica e cancellazione manuali. Quando una card è cancellata vengono rimossi
|
||||
anche i collegamenti che la coinvolgono, conservando le altre card. I collegamenti
|
||||
contribuiscono al recupero e non applicano automaticamente i contenuti.
|
||||
|
||||
La decisione architetturale è registrata nell'[ADR 0018](../adr/0018-use-postgres-for-memory-and-qdrant-for-retrieval.md).
|
||||
|
||||
### Flusso da implementare
|
||||
|
||||
Il flusso seguente traduce le decisioni approvate. I payload e l'integrazione con
|
||||
i gate sono dettagli da definire nell'implementazione, senza altre decisioni di
|
||||
prodotto pendenti.
|
||||
|
||||
1. Durante il lavoro il core individua possibili conoscenze riutilizzabili a partire
|
||||
da decisioni e artefatti registrati. Una candidata esplicita cosa afferma, dove
|
||||
vale, perché è utile e su quale correzione o decisione si basa.
|
||||
2. Prima di proporne il salvataggio confronta la candidata con le card correnti.
|
||||
Un doppione esatto non richiede una nuova card; una somiglianza semantica non
|
||||
autorizza da sola a eliminare o sovrascrivere una conoscenza.
|
||||
3. Alla conclusione del lavoro presenta un riepilogo editabile delle aggiunte e
|
||||
degli aggiornamenti proposti. Il reviewer può correggere il contenuto, restringere
|
||||
l'ambito e scegliere cosa salvare; approvare la query non equivale ad approvare
|
||||
ogni generalizzazione ricavata dalla query.
|
||||
4. Una correzione alla stessa regola nello stesso ambito propone un aggiornamento
|
||||
esplicito della card esistente. Regole valide in ambiti diversi restano distinte;
|
||||
un conflitto irrisolto non viene risolto silenziosamente dal modello.
|
||||
5. Le card salvate sono subito consultabili in Memory management; la loro
|
||||
disponibilità al recall segue lo stato di indicizzazione. La scrittura sostituisce
|
||||
il contenuto corrente senza introdurre una cronologia delle Memory.
|
||||
|
||||
La creazione manuale da Memory management resta disponibile in qualsiasi momento
|
||||
e non dipende dal riepilogo finale di una sessione. La form richiede contenuto e
|
||||
ambito adeguati alla famiglia e identifica l'origine amministrativa.
|
||||
|
||||
Gli exemplar conservano domanda e soluzione approvata come materiale consultativo.
|
||||
Il loro salvataggio non applica le scelte di quella soluzione a domande successive.
|
||||
La distribuzione del consumo nei passaggi pertinenti è decisa in Q3. Restano da
|
||||
definire i payload e l'integrazione con i gate esistenti, compreso il contesto necessario
|
||||
a proporre una regola di collegamento o di calcolo e a registrarne l'approvazione.
|
||||
|
||||
### Scenari per verificare il design
|
||||
|
||||
| Evento | Esito atteso |
|
||||
| --- | --- |
|
||||
| Il reviewer corregge un join perché il codice commessa si ripete fra esercizi e approva la spiegazione. | Proporre la regola con entrambe le chiavi e l'ambito delle tabelle interessate. |
|
||||
| Il reviewer chiede di limitare solo la domanda corrente al 2024. | Nessuna regola generale; mantenere il periodo nell'eventuale exemplar. |
|
||||
| Una query conta più volte lo stesso ordine e la correzione viene spiegata e approvata. | Proporre una card che descrive la granularità corretta e il rischio di duplicazione. |
|
||||
| Una query fallisce per timeout o una memory non viene selezionata. | Nessuna nuova regola dedotta automaticamente dall'evento. |
|
||||
| La candidata ripete esattamente una regola già presente nello stesso ambito. | Evitare una nuova card duplicata. |
|
||||
| Una nuova regola corregge una card dello stesso ambito. | Mostrare la sostituzione proposta prima del salvataggio; conservare poi solo il contenuto corrente. |
|
||||
| Due regole differenti valgono per processi o tabelle differenti. | Conservare entrambe con ambiti espliciti, senza generalizzarle al workspace intero. |
|
||||
| Il reviewer risolve un contrasto fra Memory ed Evidence. | Mostrare una correzione esplicita degli archivi; applicare i percorsi distinti per Memory ed Evidence. L'accettazione autorizzata della correzione Evidence avvia anche l'attivazione; indicare esito, operazione in corso o errore. |
|
||||
| Una sincronizzazione riuscita accerta la rimozione di una colonna da cui dipende una card. | Cancellare la card dipendente e rimuoverla dai risultati di ricerca. |
|
||||
| La connessione al DWH fallisce oppure vengono puliti solo metadati del Catalog. | Non interpretare l'evento come prova di rimozione della colonna e non cancellare Memory per quel motivo. |
|
||||
|
||||
## Differenza rispetto al runtime corrente
|
||||
|
||||
`harness/tht/memory/core.py` limita `REUSABLE_TYPES` a `concept_clarified`.
|
||||
Anche il contratto Pi di F2 ammette soltanto questi chiarimenti; gli exemplar
|
||||
`solved_question` hanno già un percorso distinto di consultazione.
|
||||
|
||||
Il perimetro concordato amplia quindi il modulo Memory. Il design deve distinguere
|
||||
la conoscenza riutilizzabile dall'evento di workflow che l'ha originata, e aggiornare
|
||||
insieme estrazione, validazione, persistenza, recall e gate. Aggiungere alla whitelist
|
||||
tutti i tipi delle decisioni SQL o sulle tabelle promuoverebbe anche scelte occasionali
|
||||
e non realizza il requisito.
|
||||
|
||||
## Funzioni
|
||||
|
||||
- Elenco paginato e ordinabile, ricerca per testo o identificatore.
|
||||
- Filtri combinabili per workspace, famiglia/kind, concetti, tabelle e colonne
|
||||
quando presenti, provenienza e data di aggiornamento.
|
||||
- Dettaglio completo: titolo, contenuto, ambito, motivazione e provenienza disponibile.
|
||||
- Creazione manuale di una card, distinguibile da una card prodotta dal workflow;
|
||||
la creazione manuale non inventa una sessione o una decisione di origine.
|
||||
- Modifica dei campi consentiti dalla famiglia, con validazione e annullamento.
|
||||
- Cancellazione del record e rimozione delle sue proiezioni ricercabili.
|
||||
- Indicazione di contenuti salvati ma non ancora disponibili al recall, con retry
|
||||
dell'operazione necessaria a renderli disponibili.
|
||||
|
||||
L'elenco amministrativo legge i record persistiti senza richiedere embedding o
|
||||
ricerca per similarità. Un'indisponibilità dell'archivio deve produrre un errore
|
||||
esplicito, distinguibile da un elenco vuoto. I filtri sono applicati sull'intero
|
||||
archivio, prima della paginazione, e non sui soli risultati del recall.
|
||||
|
||||
## Comportamento delle modifiche
|
||||
|
||||
Una modifica sostituisce il contenuto corrente. Non si introducono revisioni storiche,
|
||||
snapshot dedicati alle vecchie sessioni o migrazioni per conservarne il comportamento.
|
||||
La cancellazione toglie la card dall'archivio e dal recall ordinario.
|
||||
|
||||
La mutazione deve aggiornare o invalidare ogni proiezione interessata. Un errore
|
||||
dell'indice non può essere presentato come piena disponibilità del nuovo contenuto,
|
||||
né permettere di usare silenziosamente il contenuto eliminato o sostituito.
|
||||
La strategia di consistenza e di retry appartiene al design tecnico del modulo.
|
||||
|
||||
Il salvataggio esplicito dell'amministratore cura il contenuto condiviso. Il suo
|
||||
successivo consumo nel core mantiene la semantica della famiglia: le Memory vengono
|
||||
proposte secondo i gate del workflow, gli exemplar restano consultativi.
|
||||
|
||||
## Piano esecutivo
|
||||
|
||||
### M1 — Archivio e CRUD amministrativo
|
||||
|
||||
Definire nel modulo `harness/tht/memory/` il contratto delle card: identità stabile,
|
||||
workspace, contenuto, famiglia, ambito, motivazione, provenienza e dati specifici
|
||||
delle domande risolte. I riferimenti allo schema identificano database, tabella e
|
||||
colonna senza affidarsi alla sola presenza di nomi nel testo. Le card manuali
|
||||
non richiedono sessioni inventate.
|
||||
|
||||
Implementare un repository PostgreSQL del modulo con card, collegamenti e dipendenze.
|
||||
La transazione aggiorna insieme il contenuto e le modifiche correlate; la propagazione
|
||||
a Qdrant avviene nello stesso flusso di salvataggio. Conservare un'indicazione
|
||||
persistente dell'operazione incompleta, sufficiente anche a ripulire cancellazioni
|
||||
dopo un riavvio; il recupero usa un retry esplicito. Non servono una coda generale,
|
||||
un nuovo worker o una sincronizzazione continua. Un risultato indicizzato
|
||||
con contenuto superato o privo di card autorevole non può essere usato dal recall.
|
||||
Gli exemplar passano anch'essi dall'archivio autorevole. La transizione dal registro
|
||||
JSONL non introduce scritture doppie permanenti o compatibilità storica delle sessioni.
|
||||
|
||||
Esporre attraverso il backend elenco filtrato prima della paginazione, dettaglio,
|
||||
creazione, aggiornamento, cancellazione, gestione dei collegamenti ed esito della
|
||||
propagazione. Le operazioni chiamano la logica del harness e applicano controllo
|
||||
amministrativo e isolamento del workspace. La UI legge il repository attraverso
|
||||
queste API anche quando il servizio di embedding o Qdrant è indisponibile.
|
||||
|
||||
Consegnare Memory management nell'AppShell con form, contenuto completo, gestione
|
||||
dei collegamenti e feedback di salvataggio/indicizzazione. Verificare persistenza
|
||||
PostgreSQL, rollback delle mutazioni correlate, aggiornamento e rimozione dal recall,
|
||||
retry dopo errore dell'indice, filtri sull'intero archivio e autorizzazioni. Una
|
||||
cancellazione elimina i collegamenti incidenti conservando le altre card.
|
||||
|
||||
### M2 — Ricerca ibrida e collegamenti
|
||||
|
||||
Estendere l'adapter Qdrant alla ricerca dense e lessicale della Memory e applicare
|
||||
l'ambito anche ai risultati raggiunti attraverso collegamenti. Le card iniziali
|
||||
alimentano l'espansione limitata nel core; deduplicazione, gestione dei cicli e
|
||||
limiti espliciti impediscono una visita incontrollata dell'archivio. I risultati
|
||||
vengono riordinati insieme e risolti contro il contenuto autorevole corrente.
|
||||
|
||||
Verificare card attese, esclusioni per ambito, cicli, collegamenti verso card rimosse
|
||||
e rigenerazione dell'indice da PostgreSQL. Quando si verifica il recupero effettivo,
|
||||
usare il percorso di embedding e ricerca configurato su un indice isolato: un fake
|
||||
che restituisce gli ID predisposti verifica soltanto il contratto applicativo.
|
||||
La separazione fra le collezioni Reference e Memory rimane quella degli ADR 0017 e 0018.
|
||||
|
||||
### M3 — Workflow e sincronizzazione fisica
|
||||
|
||||
Aggiornare insieme contratti, CLI, regole Pi e widget necessari al riepilogo finale
|
||||
modificabile. Il salvataggio applica soltanto card e collegamenti selezionati; le
|
||||
nuove categorie entrano nei gate pertinenti. Il recupero di una regola non ne
|
||||
costituisce approvazione, e l'exemplar continua a essere consultativo.
|
||||
|
||||
Collegare la sincronizzazione fisica del Catalog alla pulizia delle dipendenze nel
|
||||
modulo Memory con una chiamata diretta dopo l'applicazione riuscita dello schema,
|
||||
con copertura del controllo e riferimenti rimossi. Per recuperare un'interruzione
|
||||
fra applicazione e pulizia, conservarne lo stato pendente oppure verificare di
|
||||
nuovo le dipendenze contro lo snapshot fisico riuscito e il suo ambito: il nuovo
|
||||
diff da solo perderebbe le rimozioni già applicate. La pulizia è ripetibile e
|
||||
non richiede un sistema generale di consegna eventi.
|
||||
Un confronto parziale non prova la rimozione di elementi fuori dall'ambito controllato.
|
||||
La pulizia aggiorna archivio, collegamenti e proiezioni senza un'azione manuale ulteriore.
|
||||
|
||||
Verificare selezioni e rifiuti nel riepilogo, contenuto manuale, categorie ammesse,
|
||||
notifica di rimozione fisica, errore di connessione e cleanup del solo Catalog.
|
||||
Integrare le correzioni che riguardano Evidence nell'incremento congiunto X1, dopo
|
||||
il completamento del relativo servizio di authoring e attivazione.
|
||||
|
||||
L'evoluzione interna è decisa in Q7; ricerca ibrida e grafo nel core in Q8;
|
||||
PostgreSQL autorevole in Q9; gestione dei collegamenti in Q10. I contratti tecnici
|
||||
di persistenza, indicizzazione e API devono attuare queste decisioni. Apprendimento
|
||||
automatico da rifiuti non spiegati e consolidamento automatico restano fuori dal
|
||||
perimetro concordato; gli errori compresi e approvati rientrano nei contenuti decisi.
|
||||
|
||||
## Criteri di completamento
|
||||
|
||||
- Accesso amministrativo indipendente da sessioni e da Database management.
|
||||
- Tutti i record sono raggiungibili con elenco, filtri e paginazione, senza dipendere
|
||||
dalla disponibilità di embedding e recall semantico.
|
||||
- Creazione, modifica e cancellazione persistono dopo riapertura della pagina.
|
||||
- Dopo una mutazione completata il recall usa il contenuto corrente; i record
|
||||
cancellati non riappaiono dopo reindicizzazione o preprocessing.
|
||||
- Errori di salvataggio e indicizzazione sono distinguibili e recuperabili.
|
||||
- API e interfaccia rispettano isolamento dei workspace e accesso amministrativo.
|
||||
- Nessuna operazione del CRUD modifica Evidence o metadati del database.
|
||||
- Non vengono richieste compatibilità storica o conservazione delle sessioni esistenti.
|
||||
- Le quattro categorie concordate sono rappresentabili senza promuovere le scelte
|
||||
occasionali a regole generali; gli scenari di ammissione verificano il confine.
|
||||
- La rimozione fisica accertata di una dipendenza elimina le card interessate;
|
||||
errori di connessione e cleanup del Catalog non vengono scambiati per rimozioni.
|
||||
- Le scelte sui conflitti producono correzioni persistenti esplicite secondo Q4.
|
||||
- La verifica rispetta Q6, separando contratti funzionali e casi di generazione reale.
|
||||
- Il recupero combina ricerca ibrida, filtri d'ambito e collegamenti espliciti fra
|
||||
card; la gestione del grafo non richiede un servizio di database aggiuntivo.
|
||||
- Card, collegamenti e dipendenze hanno un'unica fonte autorevole PostgreSQL;
|
||||
la rigenerazione di Qdrant conserva il contenuto corrente e le cancellazioni.
|
||||
- I collegamenti sono curabili nel riepilogo e in Administration; cancellare una
|
||||
card elimina i suoi collegamenti senza cancellare altre card.
|
||||
@@ -0,0 +1,112 @@
|
||||
# X1 — validation of session archive corrections
|
||||
|
||||
Date: 2026-09-09. The joint Memory/Evidence repair increment is implemented.
|
||||
The authoritative contract is [Session archive corrections](../contracts/archive-repair.md).
|
||||
|
||||
## Delivered behavior
|
||||
|
||||
The session gate shows complete before/after content for specific alternatives targeting
|
||||
Memory or Evidence. The reviewer chooses one correction or rejects all proposals as
|
||||
inadequate and requests reformulation. The resulting receipt survives interruption;
|
||||
saved content and index activation are reported separately. Pending activation offers
|
||||
retry of the same chosen operation. A subsequent curator change blocks replay.
|
||||
|
||||
Application requires an administrator in the harness and the responding browser
|
||||
principal's archive-management permission. Cross-principal runtime responses cannot
|
||||
misattribute the correction. A non-administrator can decline or continue the current
|
||||
question without modifying shared archives. The gate does not advance a workflow phase.
|
||||
|
||||
Memory and Evidence remain separate domains. The integration coordinator reuses their
|
||||
canonical persistence and activation operations. A session Evidence correction requires
|
||||
a consolidated archive, preserves source lineage, and cannot publish unrelated external
|
||||
edits. Existing administration, source import, dependency cleanup and final Memory review
|
||||
remain available. No automatic Git commit or push was added.
|
||||
|
||||
## Verification
|
||||
|
||||
- Harness regression: **1,264 passed**, one skipped, five deselected. All **nine**
|
||||
portable-path checks passed separately without `THT_HOME`. Python lint passed on changed modules.
|
||||
- Backend: **1,366 passed**, 40 skipped. Tests include actual session-response routes
|
||||
for both target archives, unauthorized response, malformed choice and runtime ownership.
|
||||
- Frontend: complete suite **645 passed**; the final display adjustment passed all four
|
||||
focused widget tests. Backend and frontend TypeScript checks passed.
|
||||
- Pi extension: **199 passed**, including closed human choices, rejection, failure/retry,
|
||||
forged selections and the updated public tool schema. The modular skill projection is
|
||||
byte-identical to its updated approved template.
|
||||
- PostgreSQL/Qdrant integration traverses the actual Python CLI for preparation,
|
||||
application and recovery inspection. Corrected Memory and Evidence are retrieved from
|
||||
real indexes, and Evidence activation preserves the Memory card. Session loading is a
|
||||
controlled fixture and embeddings are deterministic; this is not an LLM quality test.
|
||||
- Failure tests cover both targets, index outage, replay, later edits, workspace/session
|
||||
isolation, changed session context, rejection, non-admin writes, and interruption after
|
||||
the Evidence file write but before its saved receipt.
|
||||
- Playwright desktop/mobile: **one passed**. The real widget renders both alternatives,
|
||||
accepts an Evidence choice, displays pending activation and allows retry to active.
|
||||
No page errors or mobile horizontal overflow. Screenshots are
|
||||
`/private/tmp/thothii-x1-repair-desktop.png` and `/private/tmp/thothii-x1-repair-mobile.png`.
|
||||
This browser fixture controls operation outcomes; persistent behavior is tested above.
|
||||
- Strict MkDocs build and `git diff --check` passed.
|
||||
|
||||
## Local installation and reviewer acceptance
|
||||
|
||||
Core and frontend images were rebuilt from this worktree using the existing local
|
||||
preview launcher. Migration `004_archive_repairs.sql` was applied to the existing
|
||||
installation catalog. The new gate is available to session workflows; it is not an
|
||||
always-visible administration panel. Existing PSD archive content was not changed by
|
||||
the synthetic validation cases.
|
||||
All five local services are healthy at `http://127.0.0.1:8080/`.
|
||||
|
||||
The technical increments and their planned checks are complete. The end-user acceptance
|
||||
check remains a real session containing a meaningful domain conflict, with the reviewer
|
||||
evaluating the proposed correction. Automated browser validation uses temporary accounts
|
||||
and data, not the user's authenticated PSD session. Source import retains its E3
|
||||
validation boundaries; no broader model-quality benchmark was added.
|
||||
|
||||
## Follow-up acceptance: configured model
|
||||
|
||||
The opt-in `test_real_model_proposes_a_reviewable_persistent_archive_correction`
|
||||
passed with the installation's **zai/glm-5.3** model. Synthetic Memory asserted an
|
||||
order-ID-only join; synthetic Evidence required the financial year too. The model
|
||||
returned two schema-valid, specific alternatives with complete content and the exact
|
||||
target revisions. The test reviewer selected Memory, persisted the correction through
|
||||
the real coordinator and PostgreSQL, and retrieved the updated rule. Evidence stayed
|
||||
unchanged. This test uses deterministic vectors and the configured completion helper;
|
||||
it does not claim a full autonomous Pi session or human acceptance of PSD semantics.
|
||||
|
||||
The run log is `/private/tmp/x1-acceptance-model.log`. Reproduce with
|
||||
`THT_MEMORY_L2_INSTALLATION=<installation.yaml>` and `THT_MEMORY_L2_CORE=<core-container>`
|
||||
using `pytest -q -s -m l2 tests/memory/test_administration.py -k real_model_proposes`.
|
||||
Credentials are resolved inside core and are not returned to the test runner.
|
||||
|
||||
## Follow-up acceptance: both administration pages
|
||||
|
||||
The opt-in `frontend/e2e/memory-real.spec.ts` passed through real authentication,
|
||||
Fastify, ThtRunner, Python, isolated PostgreSQL and Qdrant. It verifies:
|
||||
|
||||
- Database management, Memory management and Evidence management appear as peers in
|
||||
that order, with no active core session or DWH binding required.
|
||||
- Memory creation, editing, persistence across backend restart, deletion and absence
|
||||
from subsequent recall.
|
||||
- Canonical Evidence remains intact after the Memory deletion. Its full rule is read
|
||||
through the real Evidence administration worker; content filtering finds it and an
|
||||
unmatched filter produces the empty state.
|
||||
- Requests for an unregistered workspace return 404 for both archives.
|
||||
- Desktop and mobile Evidence views render without horizontal document overflow.
|
||||
On phones, both archive pages have at least 380px of usable width at a 390px viewport.
|
||||
Navigation opens in the shared accessible dialog, closes with Escape or archive selection,
|
||||
and returns focus to the trigger after Escape.
|
||||
|
||||
The temporary PostgreSQL readiness probe now waits for TCP, avoiding the image's
|
||||
socket-only initialization server. The browser waits for Memory refresh to finish
|
||||
before leaving its page, matching the existing navigation guard. Visual inspection
|
||||
also exposed a real mobile layout issue: the fixed sidebar left only 134px for the
|
||||
Evidence page. `ArchiveNavigation` now moves that sidebar into the shared dialog below
|
||||
768px on Memory/Evidence pages. Desktop behavior is unchanged. The frontend image
|
||||
was rebuilt for the local preview.
|
||||
|
||||
Run log: `/private/tmp/x1-acceptance-browser7.log` (**one passed**).
|
||||
Screenshots: `/private/tmp/thothii-acceptance-evidence-desktop.png` and
|
||||
`/private/tmp/thothii-acceptance-evidence-mobile.png`. Reproduce with
|
||||
`THT_MEMORY_BROWSER_E2E=1 npx playwright test e2e/memory-real.spec.ts` from `frontend/`.
|
||||
The fixture removes its temporary containers, accounts and checkout on completion.
|
||||
The TypeScript check, Python lint, strict documentation build and diff check also pass.
|
||||
@@ -0,0 +1,67 @@
|
||||
# Evidence E1 — validation
|
||||
|
||||
Date: 2026-09-09. Scope: editable Curated Evidence v4 and the persistent local archive.
|
||||
|
||||
## Implemented behavior
|
||||
|
||||
- Parser, renderer, authoring output and normalization share the existing typed payloads.
|
||||
Visible Markdown edits determine content for all eight kinds. Legacy v1–v3 conversion
|
||||
is explicit and lossless, with errors for content that cannot be represented exactly.
|
||||
- Manual declarations record the curator. A correction preserves the original document
|
||||
as lineage, separately from the current declaration. No source hash is needed to
|
||||
create a manual file.
|
||||
- The local archive records baselines, immutable candidates, active revisions and
|
||||
deletion/source suppression metadata. Unresolved review items and invalid edits block
|
||||
consolidation. Missing archive directories are availability failures, not deletions.
|
||||
- Activation failures preserve the previous active revision. Interrupted normalization
|
||||
replays only unchanged input bytes; later operator edits survive recovery.
|
||||
- Revision-checked correction methods reject stale workflow updates. Legacy preparation
|
||||
and resolution cannot overwrite an initialized local archive; explicit import/refresh
|
||||
integration is deferred to E3.
|
||||
|
||||
## Verification
|
||||
|
||||
The final harness suite excluding opt-in L0/L2 and portable-layout cases passed with
|
||||
**1,180 tests** (58 deselected). All **9 portable-layout tests** passed separately with
|
||||
`THT_HOME` unset. The dedicated real-Qdrant integration test passed, including the
|
||||
optional 35-unit PSD probe. Ruff passed on the changed Evidence implementation and
|
||||
tests, and the strict documentation build succeeded. No frontend or backend TypeScript
|
||||
changes are part of E1.
|
||||
|
||||
The integration test uses an isolated Qdrant 1.18.2 container, the actual corpus
|
||||
pipeline, semantic chunking, vector adapter and active Evidence searcher. Deterministic
|
||||
three-dimensional embeddings isolate file/content correctness from model behavior.
|
||||
It verifies that raw edits do not change recall, consolidation updates recalled content
|
||||
and curator identity, a blocked candidate preserves prior recall, and deletions remove
|
||||
recall. Existing schema and Memory records survive each operation.
|
||||
|
||||
All **35 PSD units** were copied from the owner's workspace into
|
||||
`/private/tmp/thothii-e1-psd.bsW4cp`. Deterministic conversion preserved every ID, payload,
|
||||
scope, provenance and review item. There were no unresolved review items. The optional
|
||||
integration probe then indexed all 35 converted units and compared their complete ID
|
||||
set to the original. It uses PSD's actual `max_chunk_chars: 5000`; a preliminary probe
|
||||
at 4000 correctly blocked an oversized atomic unit.
|
||||
|
||||
Reproduce the isolated real-corpus probe after creating a converted workspace copy:
|
||||
|
||||
```sh
|
||||
cd harness
|
||||
THT_E1_PSD_COPY=/absolute/path/to/converted-copy \
|
||||
.venv/bin/pytest -q -s tests/test_evidence_editable_integration.py
|
||||
```
|
||||
|
||||
The environment variable is optional. Ordinary CI uses only synthetic Evidence. No
|
||||
source refresh, external document download, DWH call or model request is involved.
|
||||
|
||||
## Delivery boundary
|
||||
|
||||
E1 is a core/library increment. E2 must add the installed manual consolidation command,
|
||||
connect runtime source selection to the active local snapshot, and build administrative
|
||||
list/filter/detail with real persistent host paths and manual Git instructions. E3
|
||||
adds source acquisition and explicit refresh/conflict handling. X1 later wires deliberate
|
||||
joint Memory/Evidence corrections into review gates.
|
||||
|
||||
The actual PSD Evidence checkout was not converted. The live Docker preview at
|
||||
`http://127.0.0.1:8080` remains the previously deployed M3 stack, with no new Evidence
|
||||
administration page. The corpus conversion and reindexing described here used copies
|
||||
and disposable test resources.
|
||||
@@ -0,0 +1,86 @@
|
||||
# Evidence E2 — validation
|
||||
|
||||
Date: 2026-09-09. E2 is implemented locally and installed on the existing Docker preview.
|
||||
E3 source imports/refresh and X1 deliberate Memory/Evidence workflow corrections remain open.
|
||||
|
||||
## Delivered behavior
|
||||
|
||||
- Independent **Administration → Evidence management**, after Memory, protected by
|
||||
`evidence.manage`: complete typed content, provenance and original excerpts, review items,
|
||||
pagination, search, kind/purpose/status and scope/source filters, sort, and refresh.
|
||||
- Working-file states distinguish active, modified, new, removed, invalid, legacy and review
|
||||
required. Detail shows the actual configured host path with copy controls. Instructions
|
||||
cover external editing, all eight Markdown templates, consolidation and manual Git.
|
||||
- Installed `tht workspace evidence consolidate --workspace <id> [--json]` uses a closed
|
||||
maintenance envelope. First use converts legacy units. Validation, immutable candidates,
|
||||
activation and retry run through the existing corpus pipeline without a DWH scan or Git.
|
||||
- Runtime and ordinary preprocessing consume the active local snapshot. Unconsolidated
|
||||
edits remain excluded. Catalog/Schema readiness is not advanced by this operation.
|
||||
Clear preserves curated files, archive metadata and Memory; full preprocessing must
|
||||
recreate the missing Reference/Schema derivations afterward.
|
||||
- Immutable runtime lease filenames now identify rendered bytes as well as logical input
|
||||
identity. This fixes upgrades colliding with old runtime files without changing Catalog
|
||||
fingerprints or removing the checks against tampered files.
|
||||
|
||||
## Automated checks
|
||||
|
||||
The complete backend suite passed: **1,355 tests**, 40 skipped. The complete frontend
|
||||
suite passed: **639 tests**. Both TypeScript checks passed. Native Go workspace operation
|
||||
and CLI tests passed, including rejection of arbitrary consolidation flags. Ruff passed
|
||||
for changed Python implementation and test files.
|
||||
|
||||
The harness run passed **1,248 tests**, with one skipped and five deselected. Its three
|
||||
portable-path tests failed because that run deliberately set `THT_HOME` to the test
|
||||
runtime; rerunning the portable tests with `THT_HOME` unset passed. The final focused
|
||||
administration/path suite passed all 18 tests, including actionable migration errors and invalid
|
||||
consolidation combinations rejected before cleanup or indexing.
|
||||
|
||||
The real-Qdrant integration test exercised the actual harness consolidation CLI with
|
||||
deterministic embeddings: all 35 PSD units converted and indexed with stable identities;
|
||||
active-only source selection; separate Schema and Memory canaries; Clear and rebuild
|
||||
from the retained snapshot. Unit tests cover validation, saved-but-unindexed failure,
|
||||
retry, browsing/filtering, no automatic Git, and no Catalog mutation from consolidation.
|
||||
|
||||
A temporary Git repository and bare local remote exercise the documented manual sequence:
|
||||
edit, add and remove files, consolidate, inspect, stage the complete Evidence tree,
|
||||
commit, push and clone. The clone retains changed content, additions, deletions, managed
|
||||
metadata and an accessible active snapshot. No remote user repository was pushed.
|
||||
|
||||
## Installed preview
|
||||
|
||||
The existing Compose project is `thothii-18998cca7b0a`, at `http://127.0.0.1:8080`.
|
||||
The persistent editable checkout is:
|
||||
|
||||
```text
|
||||
/Users/mp/projects/ThothII/deploy/psd/evidence-registry/repo/psd-clinical/evidence
|
||||
```
|
||||
|
||||
The original registry checkout was copied from its retained Docker volume. The original
|
||||
author repository was not changed. Core and maintenance share a nested host bind for
|
||||
`repo`; registry state/snapshots and all other existing data volumes were retained.
|
||||
The installation descriptor includes the existing workspace bindings and the new
|
||||
`evidence-host.yaml` override. The previous descriptor and native binary are backed up
|
||||
at `/private/tmp/thothii-installation-before-e2.yaml` and `/private/tmp/tht-before-e2`.
|
||||
|
||||
The real installed command succeeded with **35 documents, 35 chunks, 35 changed, zero
|
||||
removed**, using the configured embedding service and Qdrant. A second run succeeded
|
||||
with **35 unchanged, zero changed**. Reading the actual archive from core returned
|
||||
35 active units and no file errors. All five long-running services are healthy.
|
||||
Only the Evidence stage ran. The strict documentation build and `git diff --check`
|
||||
also passed. The stack launcher is `bash /private/tmp/thothii-memory-preview.sh`; keep its
|
||||
worktree image-build override until this branch is integrated into the main checkout.
|
||||
|
||||
Browser verification reached the local login page. The saved administrator password
|
||||
does not match the current account hash, so the authenticated visual check remains
|
||||
manual. No account or password was modified. React interaction tests cover navigation,
|
||||
detail, host paths, templates, filtering, pending activation and invalid files.
|
||||
|
||||
## Boundaries
|
||||
|
||||
There is no web content editor, watcher, automatic commit/push, or implicit source refresh.
|
||||
The API exposes administration reads and consolidation; the archive's revision-checked
|
||||
save/remove operations remain available for the later explicit workflow corrections.
|
||||
These gates are not claimed as implemented by E2. Initialized local archives retain
|
||||
structural/review checks but bypass the legacy fixed retrieval-evaluation fixture so
|
||||
its old expected IDs cannot veto deliberate deletions. A general retrieval benchmark
|
||||
is outside the agreed scope.
|
||||
@@ -0,0 +1,100 @@
|
||||
# Evidence E3 — validation
|
||||
|
||||
Date: 2026-09-09. Explicit source import/refresh and decisions are implemented. X1,
|
||||
the integration of deliberate Memory/Evidence corrections into workflow gates, remains next.
|
||||
|
||||
## Delivered behavior
|
||||
|
||||
The independent Evidence page now offers **Sources and imports**. An operator copies
|
||||
a specialist's draft into `evidence/incoming/`, then explicitly imports/refreshes.
|
||||
Original local Markdown and configured HTTP/S3 sources use existing read-only adapters.
|
||||
Acquisition retains raw bytes, source identity and versioned normalized documents.
|
||||
The existing Pi authoring refiner prepares typed, editable v4 proposals.
|
||||
|
||||
Unchanged hashes skip refinement. All source acquisitions/refinements must succeed
|
||||
before saving a new set of comparisons. Missing sources are recorded as unavailable,
|
||||
never interpreted as permission to delete. No runtime lookup, ordinary consolidation
|
||||
or preprocessing triggers remote refresh once the local archive is initialized.
|
||||
|
||||
The administrator sees current and proposed units, scope, content, excerpts, review
|
||||
items and explicit retirement IDs. **Keep local Evidence** records the retained wording
|
||||
as a manual declaration with original lineage. **Use proposed Evidence** adopts the
|
||||
proposal and its source version. Both save and activate through the existing archive
|
||||
and corpus pipeline; review items block adoption. Comparisons use optimistic checks
|
||||
on affected file bytes. Interrupted decisions have a durable replay journal and retry
|
||||
without reacquisition, while intervening external edits are preserved and reported.
|
||||
|
||||
Deleted IDs remain reserved. New model-generated identities from sources with curated
|
||||
deletions are also conservatively suppressed; surviving IDs can still receive reviewed
|
||||
updates. Deliberate new knowledge can be authored as a manual file. This mechanical
|
||||
protection does not depend on the model detecting semantic duplication or contradictions.
|
||||
|
||||
Installed commands are `workspace evidence refresh` and `workspace evidence decide`,
|
||||
alongside E2 consolidation. Decision envelopes carry a source identity, comparison
|
||||
revision and keep/replace choice. Extra URLs, arbitrary paths, forged actors and unknown
|
||||
fields are rejected at the public API/CLI boundary. HTTP requests bind the authenticated
|
||||
curator. Source operations do not mutate Catalog readiness or run DWH/schema stages.
|
||||
The Python source worker is internal; the workflow CLI's visible surface is preserved.
|
||||
|
||||
## Checks
|
||||
|
||||
- Complete backend suite: **1,359 passed**, 40 skipped. Complete frontend suite:
|
||||
**641 passed**. Both TypeScript checks passed; native Go CLI/workspace tests passed.
|
||||
- Harness regression run: **1,256 passed**, one skipped and five deselected, with
|
||||
portable-path tests run separately without `THT_HOME`. All **24 focused import,
|
||||
CLI-surface and portable-path checks** passed. These
|
||||
cover import, unchanged refresh, access failure, missing source, manual correction,
|
||||
keep/replace, deletion suppression, stale comparisons, failure/retry and interrupted
|
||||
journal writes. Ruff passed on the changed Python implementation and tests.
|
||||
- The real-Qdrant test traverses the actual harness source CLI with deterministic
|
||||
refinement/embedding boundaries: import is absent from recall before a decision,
|
||||
accepted content becomes searchable, refreshed proposals preserve active manual
|
||||
corrections, replacement removes the former text, deletion remains absent after
|
||||
another refresh, and unrelated Schema/Memory canaries survive.
|
||||
- Source contract fixtures cover controlled HTTP and S3 identities, exact acquired
|
||||
bytes, and acquisition call counts. Existing adapter tests retain transport/egress
|
||||
coverage. The test does not claim to exercise a live S3 account.
|
||||
- React interaction tests verify explicit refresh, comparison content, exact decisions,
|
||||
saved-decision retry and failure feedback. Route tests cover admin authorization,
|
||||
workspace isolation, strict inputs and principal attribution. Service tests verify
|
||||
the trusted config file descriptor and absence of Catalog mutation.
|
||||
|
||||
## Local preview
|
||||
|
||||
Core/frontend were rebuilt for the existing `thothii-18998cca7b0a` stack. Its persistent
|
||||
archive and data volumes are retained. The native `/usr/local/bin/tht` was updated;
|
||||
the previous executable is at `/private/tmp/tht-before-e3`.
|
||||
|
||||
The installed refresh command ran against `psd-clinical` successfully: **35 unchanged
|
||||
sources, zero changed, zero pending comparisons**. All 35 source hashes matched their
|
||||
existing units, so this probe required no refinement and changed no active Evidence.
|
||||
Source registry metadata was saved locally; no Git commit or push was performed.
|
||||
|
||||
A separate synthetic draft was passed to the configured Pi/model inside core. It
|
||||
produced one domain proposal with one review item, which was not activated. The probe
|
||||
exposed a deployment issue: Python wheel modules and Pi skills live in different
|
||||
directories. The refiner now resolves resources through `THT_HARNESS_DIR`, with the
|
||||
source-tree location as its development fallback; a regression test covers this layout.
|
||||
|
||||
The corrected installed worker was then exercised end to end in a temporary workspace
|
||||
inside core, using the real configured Pi/model and a synthetic `incoming/orders.md`.
|
||||
It returned success, one changed source, one comparison and one proposal with a review
|
||||
item. The active snapshot remained absent. The temporary directory was removed on exit;
|
||||
the probe did not open the DWH or activate an index. Strict docs build and
|
||||
`git diff --check` also passed.
|
||||
|
||||
The in-app browser still showed the login page with the prior credential error.
|
||||
Authenticated visual verification remains manual; no credentials were reset or retried.
|
||||
|
||||
## Operational instructions and boundaries
|
||||
|
||||
See [Import drafts and refresh sources](../contracts/curated-evidence-v4.md#import-drafts-and-refresh-sources)
|
||||
for commands, local paths, review, retry and backup/Git requirements. Preserve the
|
||||
complete Evidence tree, including source comparisons, journals and acquired versions.
|
||||
Local activation and transfer to the remote Git repository remain separate operator steps.
|
||||
|
||||
No web content editor, automatic Git, background watcher, new job queue, general
|
||||
retrieval benchmark or automatic source merge was introduced. Review/refinement is
|
||||
sequential and bounded by per-source limits plus 200 documents/100 MiB per refresh.
|
||||
New changed-source decisions and failure scenarios use isolated test data; live PSD
|
||||
curated content was kept unchanged. X1 is not included in this increment.
|
||||
@@ -0,0 +1,96 @@
|
||||
# M2 — Ricerca ibrida e collegamenti
|
||||
|
||||
Data: 2026-09-09. Implementazione locale dell'incremento M2 del
|
||||
[piano Memory approvato](2026-09-08-memory-management.md#piano-esecutivo).
|
||||
|
||||
## Risultato
|
||||
|
||||
La ricerca Memory ed exemplar usa embedding dense e BM25 in Qdrant. I filtri sono
|
||||
applicati in entrambi i rami prima della selezione dei candidati. Il core espande
|
||||
i collegamenti uscenti, deduplica, limita cicli e visite, riordina insieme i risultati
|
||||
e restituisce il contenuto corrente verificato in PostgreSQL. Non usa un database
|
||||
a grafo né una chiamata LLM per il riordinamento.
|
||||
|
||||
Il contesto fisico distingue database, schema, tabella e colonna e richiede che
|
||||
corrispondano alla stessa dipendenza strutturata. Le card senza dipendenze valgono
|
||||
per il workspace; un riferimento a un antenato fisico si applica ai suoi discendenti.
|
||||
Ambito descrittivo e concetti possono restringere ulteriormente la ricerca tramite
|
||||
`--filters`. La CLI impedisce di sostituire database/schema del runtime. Il dettaglio
|
||||
dei limiti e della formula di ranking è nel [contratto operativo](../gestione-memory.md#hybrid-recall-and-links).
|
||||
|
||||
L'incremento conserva i confini dei gate correnti: F2 riceve chiarimenti di dominio,
|
||||
gli exemplar restano consultativi. Un collegamento non autorizza a consumare una
|
||||
famiglia diversa o una card fuori ambito. Il riepilogo finale, i nuovi gate e la
|
||||
pulizia delle dipendenze dopo sincronizzazione fisica appartengono a M3.
|
||||
|
||||
## Transizione e recupero
|
||||
|
||||
La migrazione versionata `002_hybrid_projection.sql` aggiunge il formato delle
|
||||
proiezioni. Le card M1 restano autorevoli e consultabili; le loro proiezioni dense
|
||||
risultano pendenti e non possono alimentare il recall. Un retry esplicito o
|
||||
`tht memory index -c <runtime.yaml>` costruisce dense e BM25 dal contenuto corrente.
|
||||
Il formato della proiezione e la revisione della card sono verificati prima dell'uso.
|
||||
|
||||
Il salvataggio può aggiungere il vettore sparse mancante nella sola collezione
|
||||
Memory. Non sostituisce configurazioni incompatibili e non modifica Reference.
|
||||
Il rebuild esplicito ricrea anche una collezione Memory assente; il test elimina
|
||||
la collezione, ricostruisce da PostgreSQL e verifica il ritorno della sola card conservata.
|
||||
Fallimenti lasciano il lavoro di propagazione persistito e recuperabile. Nessuna
|
||||
importazione da JSONL, sessioni storiche o vecchi payload Qdrant.
|
||||
|
||||
## Verifiche
|
||||
|
||||
| Controllo | Esito |
|
||||
| --- | --- |
|
||||
| Suite harness senza L0/L2, escluso il file dei percorsi portabili | 1.152 test passati nell'esecuzione finale. |
|
||||
| Suite mirata Memory, adapter e CLI, con embedding reale | 78 test passati. |
|
||||
| Verifica aggiuntiva del rebuild con collezione assente e adapter | 54 passati; il solo test del modello reale era escluso in questa riesecuzione. |
|
||||
| API Fastify Memory | 13 test passati, compresa propagazione della lingua del workspace. |
|
||||
| Browser amministrativo integrato | Passato: creazione, modifica, riavvio, rilettura, cancellazione e verifica del recall. |
|
||||
| Wheel e casi CLI | 10 test passati; il wheel include entrambe le migrazioni Memory. |
|
||||
| Build e controlli statici | Build/typecheck backend, Ruff sui file Python interessati e build documentale strict passati. |
|
||||
|
||||
- Test deterministici: collegamenti necessari, contenuto corrente, duplicati,
|
||||
cicli, profondità e limiti, card mancanti o pendenti, rifiuti già registrati,
|
||||
famiglie e ambiti esclusi, dipendenze omonime e filtri CLI vincolati al runtime.
|
||||
- Adapter: stesso filtro nei prefetch dense/BM25 per Memory ed exemplar; restano
|
||||
coperti i contratti Evidence esistenti.
|
||||
- PostgreSQL/Qdrant: salvataggio, modifica, cambio famiglia, cancellazione,
|
||||
ricostruzione, riferimento separato, isolamento, RLS, errori, retry e transizione
|
||||
delle proiezioni M1 al formato ibrido.
|
||||
- Recupero effettivo: client Ollama di produzione con il modello configurato
|
||||
`qwen3-embedding:0.6b`, dimensione 1024, e Qdrant dell'immagine fissata in Compose.
|
||||
La domanda sulla chiave commessa fra esercizi recupera la regola attesa e la
|
||||
granularità collegata, escludendo un altro database, un altro ambito e dipendenze
|
||||
che corrispondono soltanto combinando riferimenti distinti. Verifica separatamente
|
||||
dense, BM25 e fusione, poi recall, cancellazione e rebuild.
|
||||
|
||||
Il test effettivo avvia un processo Ollama separato, montando il volume del modello
|
||||
installato in sola lettura. PostgreSQL e Qdrant sono container temporanei dedicati,
|
||||
eliminati a fine test. Non usa ID di risultati predisposti. Il browser amministrativo
|
||||
usa invece embedding deterministici: verifica il collegamento fra UI, autenticazione,
|
||||
Fastify, ThtRunner e persistenza, senza essere una misura di qualità del recupero.
|
||||
|
||||
Non è una valutazione generale della qualità semantica su un corpus di produzione;
|
||||
verifica i casi di recupero richiesti da M2, con il percorso reale configurato.
|
||||
|
||||
## Riproduzione
|
||||
|
||||
Dalla directory `harness`, con Docker disponibile:
|
||||
|
||||
```sh
|
||||
THT_HOME=/private/tmp/thothii-m2-test-home \
|
||||
THT_MEMORY_TEST_OLLAMA_VOLUME=<volume-modelli-installazione> \
|
||||
THT_MEMORY_TEST_MODEL=qwen3-embedding:0.6b \
|
||||
THT_MEMORY_TEST_DIMENSIONS=1024 \
|
||||
.venv/bin/pytest -q tests/memory/test_administration.py \
|
||||
tests/memory/test_retrieval.py tests/memory/test_recall.py \
|
||||
tests/test_qdrant_vector_store.py tests/test_solved_search_cli.py
|
||||
```
|
||||
|
||||
Senza il volume esplicito, il solo test con modello reale viene escluso; gli altri
|
||||
test restano eseguibili. Il volume deve contenere il modello indicato. Le immagini
|
||||
Qdrant e Ollama del test sono lette da `compose.yaml`.
|
||||
|
||||
Consegna locale: non sono stati eseguiti deploy, migrazioni delle installazioni
|
||||
attive o aggiornamenti remoti dell'issue tracker.
|
||||
@@ -0,0 +1,78 @@
|
||||
# Memory M3 — validation
|
||||
|
||||
Implemented on 2026-09-09 in the rapid-harbor worktree.
|
||||
|
||||
## Delivered behavior
|
||||
|
||||
- F8 presents an editable summary of proposed additions, explicit updates and links.
|
||||
Only selected content is saved, including the optional solved-question exemplar.
|
||||
- Proposals reference effective approved decisions. Exact existing content is reused.
|
||||
Concurrent edits invalidate an update; manual identities and origins are preserved.
|
||||
- Selected cards and links commit atomically. Durable receipts recover repeat delivery
|
||||
and the gap before the session review marker. Finalization does not add Memory.
|
||||
- F4/F6/F7 retrieve SQL rules and explained errors for the existing approval gates.
|
||||
Retrieval is consultative and does not write an approval decision.
|
||||
- Successful Catalog physical sync deletes cards with matching removed dependencies.
|
||||
The same Catalog transaction marks pending Memory cleanup. Retry keeps the original
|
||||
removals and does not rescan; deletion receipts and projection tombstones survive restarts.
|
||||
- Migration 003 adds minimal review and physical-cleanup receipts.
|
||||
|
||||
## Executed checks
|
||||
|
||||
| Check | Result |
|
||||
| --- | --- |
|
||||
| Harness deterministic suite, excluding portable-path environment cases | 1,152 passed |
|
||||
| Portable-path suite without the temporary THT_HOME override | 9 passed |
|
||||
| Memory service/retrieval with isolated PostgreSQL and Qdrant | 41 passed, 1 optional real-embedding case skipped, 1 L2 case excluded |
|
||||
| Pi gate suite | 195 passed |
|
||||
| Backend full suite | 1,346 passed; one auth timing test exceeded 5 seconds under concurrent load |
|
||||
| Isolated auth and Catalog route rerun | All 40 passed, including the timed-out case |
|
||||
| Catalog PostgreSQL integration after adding atomic cleanup-marker coverage | All 5 passed |
|
||||
| Frontend full suite | 635 passed |
|
||||
| Chromium summary review, desktop and 390px mobile | Passed; no page errors or horizontal overflow |
|
||||
| Configured real GLM 5.3 generation | Passed on synthetic PostgreSQL data |
|
||||
| Backend/frontend production builds, modified Python lint, strict docs build | Passed |
|
||||
|
||||
The existing local Docker preview was rebuilt from this worktree, migration 003
|
||||
was applied, and core/frontend were recreated with the existing persistent volumes.
|
||||
The preview remains at `http://127.0.0.1:8080`.
|
||||
|
||||
The browser check uses the production widget in an isolated Vite fixture. It edits
|
||||
the rule, declines the exemplar, submits only the selected card and checks responsive
|
||||
layout. Gate tests separately verify request ordering through the production Pi
|
||||
composition root; service and Catalog tests use real PostgreSQL. This is not a claim
|
||||
of an automated complete live Pi conversation.
|
||||
|
||||
The L2 case retrieves an approved SQL rule, excludes a card bound to another database,
|
||||
and asks the configured GLM 5.3 model to generate a query. Order IDs repeat between
|
||||
financial years; the correct composite join returns 120 on the synthetic fixture.
|
||||
The generated SQL is validated and executed in a read-only PostgreSQL transaction.
|
||||
No real DWH rows are sent. Embeddings in this case are deterministic; the real
|
||||
embedding/hybrid retrieval evidence remains documented in M2.
|
||||
|
||||
## Reproduction
|
||||
|
||||
From the harness:
|
||||
|
||||
```sh
|
||||
THT_HOME=/private/tmp/thothii-m1-harness-home .venv/bin/pytest -q -m 'not l0 and not l2' --ignore=tests/test_portable_paths.py
|
||||
.venv/bin/pytest -q tests/test_portable_paths.py
|
||||
THT_HOME=/private/tmp/thothii-m1-harness-home .venv/bin/pytest -q tests/memory/test_administration.py tests/memory/test_retrieval.py -m 'not l2'
|
||||
npm test
|
||||
```
|
||||
|
||||
The optional generation case requires an installation YAML path and its running
|
||||
core container. It resolves the model credential inside core without printing it:
|
||||
|
||||
```sh
|
||||
THT_MEMORY_L2_INSTALLATION=<installation.yaml> THT_MEMORY_L2_CORE=<core-container> \
|
||||
.venv/bin/pytest -q -s -m l2 tests/memory/test_administration.py -k real_model
|
||||
```
|
||||
|
||||
From frontend: `npx playwright test e2e/memory-review.spec.ts`.
|
||||
Screenshots are written to `/private/tmp/thothii-m3-summary-desktop.png` and
|
||||
`/private/tmp/thothii-m3-summary-mobile.png`.
|
||||
|
||||
Evidence authoring and the joint X1 persistent Memory/Evidence conflict repair remain
|
||||
outside M3. This increment does not infer knowledge from unexplained failures or
|
||||
promise general improvements in SQL-generation accuracy.
|
||||
Reference in New Issue
Block a user