Files
obsidian-vault/personal/projects/personal-os/personal-os-evidence-graph-design-2026-10-04.md
T

96 lines
23 KiB
Markdown
Executable File
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Personal OS — контракт графа доказательств R2
> Актуальное уточнение 05.10: [шесть уровней Personal OS](/Users/admin/Developer/personal-os/planning/personal-os-six-layer-analysis-2026-10-05.md). Условия: личный доступ, открытые компоненты, без изменения систем компании. Очередность: покрытие проектов → эталон и явные связи → испытание Cognee/Graphiti → роли и важность → внимание и ретроспекция. Исследование выявило потери Asana; исправления и модельные прогоны ещё не выполнены. Корпоративный shortlist больше не определяет первый этап.
> Дополнение 04.10: [понимание потока работ и этапы WG-0–WG-4](/Users/admin/Developer/personal-os/planning/personal-os-work-graph-research-2026-10-04.md). Приоритет проверки — покрытие корпуса, обнаружение связей, текущая ситуация и роль пользователя. Это исследовательское уточнение для согласования; выбранный PostgreSQL core сохраняется, новые модели и graph runtime не внедрены.
4 октября 2026. Целевой проект для утверждения; миграции и runtime по нему не включены. Заменяет ранний иллюстративный DDL целиком. Канонический общий план: [пакет R2](/Users/admin/Developer/personal-os/planning/system-review-2026-10-04/review.md). Это спецификация будущей миграции и API, не утверждение об уже созданных таблицах.
## 1. Хранилище и граница истины
PostgreSQL — единственная каноническая БД. Raw payload хранится локально по content hash, с защищённым locator в БД. JSON, Obsidian и экраны — версионированные проекции. Таблицы существующего Asana mirror временно остаются adapter storage. Отдельная graph DB в рабочем контуре пока не выбрана. В E3 сравниваются Cognee и Graphiti: дополнительное хранилище допустимо в изолированном испытании как перестраиваемый индекс, если экспорт и согласование с канонической PostgreSQL проходят приёмку. Это заменяет прежний безусловный запрет на проверку готового graph runtime. Начальный поиск: exact identifiers, PostgreSQL full-text/trigram и bounded recursive queries. Embeddings подключаются только при измеренном улучшении retrieval на holdout; они не устанавливают факт связи.
Source-owned поле и интерпретация различаются: GitHub определяет merge конкретного PR, Asana — назначение задачи, Алекс — намерение/цель. Фраза на встрече свидетельствует о сказанном и может обосновать decision; она сама не доказывает release. Статусы proposal/decision/implementation/verification/merge/release/impact независимы.
## 2. Таблицы и ограничения
Все внутренние IDs выдаёт код при первом сохранении (UUID). Пользователь не составляет registry проектов. Внешние IDs приходят из API/индекса источника. Время хранится как timestamptz UTC; timezone пользователя применяется на границе UI/расписаний.
| Таблица | Поля и обязательные ограничения |
|---|---|
| type_definitions | PK `(namespace, name, version)`; kind entity/predicate/dimension, immutable schema_json, endpoint_types, cardinality, transitivity, acyclic, acceptance_policy. Published версия не меняется; новый тип сначала proposal. |
| entities | PK id; FK exact type version; created_at. Устойчивая идентичность не зависит от названия, каталога или владельца. |
| identifiers | id, entity_id FK, source_namespace (provider + account/workspace/repo), external_key, kind canonical/alias, valid interval, recorded_at. Один canonical key не принадлежит двум действующим сущностям; неоднозначный alias возвращает несколько кандидатов. URL нормализуется адаптером по правилам источника. |
| entity_versions | PK id; entity_id FK, version, properties JSONB по type schema, recorded_at, valid interval, source_record_id либо decision_id. UNIQUE(entity_id, version); версии immutable. Связи и спорные state fields не прячутся в properties. |
| identity_decisions | id, kind merge/split, input entity IDs, output IDs, основания, actor, recorded_at, effective_at. Старые IDs остаются разрешимыми. Split требует явного распределения identifiers; публикация перестраивает затронутые scopes. |
| source_records | id, source_namespace, source_key, source_version, payload_hash, occurred_at, fetched_at, scope, locator, privacy_class, run_id FK, tombstone. UNIQUE(namespace, key, version); конфликт одного version с другим hash — quarantine. Если source не даёт version, adapter использует hash. |
| source_spans | id, record_id FK, selector_kind, selector JSON, excerpt_hash. Text selector — offsets в сохранённом нормализованном тексте; transcript — segment ID + start/end + speaker; JSON — pointer. Selector проверяется по конкретному immutable record. |
| assertions | id, kind relation/value, subject_id FK, predicate_type FK **или** dimension_type FK, object_id FK **или** value JSONB, scope_key. CHECK: relation имеет predicate+object без dimension/value; value имеет dimension+value без predicate/object. Endpoints/value проверяются по exact type version. |
| assertion_revisions | id, assertion_id FK, revision, recorded_at, valid_from/to, review_status candidate/accepted/rejected/retracted, method, analysis_run_id/collector_run_id, policy_version, rationale. UNIQUE(assertion_id, revision); ни update, ни delete истории. Статус cancelled — значение decision, не review_status. Изменение значения создаёт новое assertion; изменение решения о нём — revision. |
| assertion_evidence | assertion_revision_id FK, span_id FK, role supports/contradicts; composite PK. Accepted fact обязан иметь supports evidence. Ограниченное пользовательское намерение имеет evidence в сохранённом feedback record. |
| derivation_inputs | output_revision_id FK, input_revision_id FK; composite PK, self/cycles запрещены. Сохраняет зависимость выводов, а не только список текстовых цитат. |
| resolutions | id, subject_id FK, dimension/scope, valid interval, resolved_at, state known/conflict/unknown, policy_version, selected_revision_id nullable. Conflict/unknown не получают выбранное значение. |
| resolution_members | resolution_id, assertion_revision_id, disposition supporting/opposing/superseded; PK пары. Все основания решения доступны, даже при разных timestamps. |
| publications | id, schema_version, generated_at, source_watermarks JSON, coverage JSON, policy_version, manifest_hash, expires_at. Publication immutable и фиксирует IDs включённых resolutions/проекций, не «последние строки» при чтении. |
| publication_members / projection_artifacts | publication_id + member kind/id; artifact kind/hash/protected locator. Current pointer меняется одной SQL транзакцией только после готовности всех обязательных artifacts. |
| source_cursors / source_runs | namespace/scope, cursor, last_success, completeness, run status/error. Cursor фиксируется после durable records; частичный run не объявляется complete. |
| outbox | id, source_run_id, affected_scope, event_hash UNIQUE, created_at, consumed_at. Записывается в транзакции records/cursor; consumer ack после durable result. |
| job_runs | id, kind, scope, input_hash, prompt_hash, policy_version, idempotency_key UNIQUE, state, lease_owner/token/until, attempt, deadline, cost/token reservation. Lease fencing запрещает опоздавшему worker публиковать результат после takeover. |
| analysis_runs | id, job_id FK, code_revision, model/provider, prompt_hash, input packet hash, output hash, duration, usage/cost or unknown, verifier verdict. Повторные attempts сохраняются раздельно. |
| feedback | id, client_request_id UNIQUE, target kind/id, publication_id, action, scope, valid_until/condition, actor, created_at, reason. Optimistic version check; устаревшая поправка пересопоставляется явно либо возвращает конфликт, не применяется молча к новой карточке. |
| plan_versions / context_versions / delivery_decisions | Immutable plan с publication_id и constraints hash; отдельный свежий context с TTL; decision записывает plan/context/policy IDs, delivery key и outcome. Каждое уведомление deduplicated по target+meaningful revision. |
DDL реализуется как additive migration с FK/CHECK/UNIQUE/индексами и transactional write API. Сложные проверки JSON schemas, endpoint compatibility и циклов выполняет единственный writer внутри транзакции; direct INSERT для analyst role запрещён. Проверка циклов блокирует соответствующий graph scope до commit, чтобы два параллельных ребра не прошли по отдельности. SQL constraints страхуют структуру, semantic verifier — смысл.
Индексы: identifiers(namespace,key), source_records(namespace,key,version), spans(record_id), assertions(subject,predicate/dimension,scope), assertions(object,predicate), revisions(assertion_id,revision DESC), evidence(span_id), derivation(input_revision_id), resolution(subject,dimension,scope), jobs(state,lease_until). GIN/full-text только для полей retrieval; произвольный JSONB не заменяет typed relations.
## 3. Типы, произвольные объекты и время
Базовые entity types: person, initiative/project, source_project, task, pull_request, repository, file, note, conversation, message, app_session, agent_run, decision, capability, contribution, career_goal, competency, feedback, work_request. Новый домен добавляет schema в каталог с namespace/version, без переписывания таблиц. Неизвестный объект сохраняется как unresolved candidate с исходным span; агент не создаёт активный тип сам.
Relation types задают направленность и допустимые endpoints: task `part_of` initiative, PR `mentions` task, decision `concerns` proposal, project `depends_on` capability, capability `delivered_by` project, project `precedes` project. `precedes` — строгий порядок без циклов; `depends_on` может фиксировать реальный цикл как отдельный conflict для планнера, а не скрывать его. Общий человек/repo/время даёт общую связь, не зависимость.
`valid_from/to` описывают время в предметной области; `recorded_at` — когда OS узнала о записи. Query «что считали тогда» использует publication на ту дату; «что теперь известно о том моменте» использует последние принятые revisions с нужным valid interval. Поздний backfill не выигрывает по fetched_at. Unknown время сохраняется явно, без придуманной даты.
Merge/split не удаляет evidence: новое identity decision и новые projection revisions. Исторические публикации открывают прежнее разрешение IDs. Зависимые claims становятся pending revalidation, пока затронутый scope не перепроверен; старый вывод не показывается как актуальный.
## 4. Установление связи и принятие вывода
1. Collector обнаруживает объекты внутри разрешённых namespaces, сохраняет source records и spans. Точные API ID, URL и memberships принимаются детерминированно с типом отношения исходного источника; упоминание PR→task остаётся mentions.
2. Retriever подбирает candidates по identifiers, тексту, времени и типам. Агент читает ограниченный immutable packet и возвращает typed candidate + supports/contradicts spans + alternatives. Proposed local IDs материализуются writer-ом после проверки, не выдаются за существующие UUID.
3. Code validator проверяет JSON, наличие/целостность span, типы, время, input version, coverage и capability. Semantic reviewer проверяет, следует ли утверждение из evidence. Другой LLM может подготовить оценку, но его согласие само по себе не даёт accepted.
4. В пилоте смысловые claims принимает человек пакетно в пределах reviewer budget; точные source facts принимаются кодом. После holdout отдельный низкорисковый класс можно перевести на автоматическую policy по явному decision record. Отмены/внедрение/release, identity merge и спорные карьерные оценки остаются на явном review до отдельной приёмки своего класса. При нехватке ревью claim остаётся candidate/unknown и не создаёт обязательный ежедневный опрос.
5. Resolver группирует по subject+dimension+scope, учитывает source authority, valid interval и явное supersession. Разные значения не считаются конфликтом, если относятся к разным периодам/предметам. При несовместимости без доказанного supersession сохраняет conflict независимо от дат. Publisher фиксирует result вместе с policy и основаниями.
Пример Core Data: предложено code-init → обсуждено → отклонено после проверки совместимости Xcode 27 → существующие модели сохранены. Cleanup и PR упаковки SwiftPM — отдельные subjects. Исследовательский вклад возможен; `implemented code-init`, release и impact из этой цепи не следуют.
## 5. Запись, повтор, invalidation и публикация
Raw file: write temp → fsync → atomic rename по hash → SQL transaction records/spans/cursor/outbox. Для повторного hash используется тот же content object. Crash до SQL оставляет orphan; GC удаляет его после grace period и проверки отсутствия DB refs. Backup согласует manifest DB с referenced payloads. Нельзя обещать общую файловую/SQL транзакцию.
Outbox events фиксируются вместе с изменениями. Dispatcher читает их с lease и помечает обработку; доставку события можно повторить, поэтому idempotency ключ включает kind/scope/input_hash/prompt_hash/policy_version. Ack не предшествует durable result. Новая версия источника делает affected derivations stale, добавляет revalidation jobs и обновляет coverage, а не запускает анализ всех проектов.
Worker делает результат локальным артефактом; validator/writer сохраняют candidates и review. Publisher строит immutable projections, записывает artifacts и members, проверяет целостность, в одной транзакции переставляет current pointer. Reader получает manifest и запрашивает projections только по его ID. ETag/hash и expires_at проверяются клиентом; partial сборка не заменяет рабочую публикацию.
R1 использует тот же publication envelope над существующим mirror; R2 переносит вычисление resolutions на graph. Schema_version позволяет клиенту отвергнуть несовместимую проекцию. Backfill/replay проверяются до cutover; migration 004 project_states не вводится как ещё один параллельный truth store. На cutover у каждого connector остаётся один scheduler owner.
## 6. Граф, проекты, карьера и приложения
API `/graph?root=<uuid>&depth=2&at=<publication>` возвращает ограниченный подграф, typed paths, evidence refs, cursor/continuation и truncation flag. Default limit 200 узлов/500 рёбер, server timeout 2 секунды; большая область раскрывается по узлу, не строится без границ. UI использует Cytoscape.js с карточкой evidence; таблица/список пути доступен без графического движка для старого iPad и печати.
Представления: карта предметной области; последовательность проектов по precedes; хронология решений проекта; карьера `цель → вклад → feedback → следующий шаг`; рабочая сессия `app_session → observed file/repo/task`. App foreground — наблюдение, не доказательство намерения; title similarity оставляет candidate. File identity включает repo/revision/path или стабильный note ID; rename хранится явно.
Косвенный путь `Project A → depends_on → Capability X → delivered_by → Project B` показывает основания каждого ребра. Он не материализуется как прямая зависимость A→B автоматически. Любое derived assertion хранит все input revisions; смена одного основания invalidates результат.
Career analyst читает accepted project resolutions и attribution: кто предложил/реализовал/проверил/принял решение. Наблюдение о карьерном пути — самостоятельный candidate, связанный с датированной целью, competency, contributions и feedback. Апрельские EP2→EP3/Advisor Readiness остаются historical до подтверждения актуальности. Из активности не выводится уровень; отсутствие evidence не равно отсутствию результата.
## 7. Приёмка контракта
AC01: чистая БД, вся migration chain, повтор, read/write roundtrip, ошибочные FK/schema/endpoints отклоняются. AC02: duplicate, late, edit/delete/rename, merge/split и bitemporal query. AC03: новый проект без ручных IDs, одинаковые названия не сливаются. AC04/05: отмена Core Data и конфликты разных дат. AC06: косвенный путь, конкурентный precedes cycle, зависимость с реальным циклом видна как conflict. AC07: вклад без release, historical goal, attribution. AC10/11: scoped correction, stale client, crash между artifacts и pointer, lease takeover, outbox replay без дубликатов. AC13: privacy projection и источниковая prompt injection.
Проверки завершаются сохранённым verdict с входами/code/prompt/policy version. Schema и эти случаи реализуются до переключения публикации на graph. Критерии SC и этапы R0–R4 определены в общем пакете, отдельной конкурирующей очереди работ здесь нет.
## 8. Первичные источники выбранных паттернов
PostgreSQL bounded recursive traversal: https://www.postgresql.org/docs/current/queries-with.html ; W3C provenance: https://www.w3.org/TR/prov-o/ ; Asana memberships: https://developers.asana.com/reference/gettask ; Graphiti temporal facts: https://github.com/getzep/graphiti ; GraphRAG indexing pipeline: https://github.com/microsoft/graphrag/blob/main/docs/index/default_dataflow.md ; Cytoscape renderer: https://js.cytoscape.org/ . Это основания проектирования, не установленные зависимости, кроме существующего PostgreSQL. На runtime-приёмке версии новых библиотек фиксируются lockfile.