[Ecosystem Gap] Complete tenant-scoped document and LLM workflows without weakening standalone operation

[seonghobae]

Buyer-visible problem

pg-erd-cloud documents Clearfolio and OpenAI-compatible LLM integration, and current PRs add narrower connector primitives. The present experience is still a set of optional calls rather than a complete buyer workflow:

• a reference document is not durably attached to a project/snapshot/object with governed provenance;
• connector failure/retry/revocation states are not one coherent UI and audit contract;
• pg-erd-cloud still accepts direct provider configuration instead of delegating model discovery, capability routing, fallback, and evaluation to contextual-orchestrator;
• tenant, purpose, authorization, data classification, and evidence lineage are not proven end to end;
• external services can therefore look like hidden runtime requirements even though pg-erd-cloud must remain fully useful by itself.

Product boundary

pg-erd-cloud remains the authority for ERD projects, connections, snapshots, diagram views, annotations, sharing, migration plans/runs, and connector references. It does not become a document viewer, object store, PIM/knowledge graph, or LLM gateway.

• Clearfolio owns document conversion/viewer jobs and artifacts.
• contextual-orchestrator owns provider/model discovery, routing, fallback, orchestration, evaluation, and cost/quality telemetry.
• naruon may consume pg-erd-cloud project/snapshot evidence through an explicit connector; it does not own pg-erd-cloud project state.
• Every integration is optional and fails as an unavailable capability, not as a broken core product.

Required vertical workflows

1. Reference-document attachment

project/snapshot/table
→ authorized attachment intent
→ signed tenant/purpose request
→ Clearfolio conversion job
→ durable connector receipt
→ viewer artifact reference
→ project evidence drawer

Required behavior:

• normalized connector_account, connector_grant, document_reference, attachment_binding, connector_job, and connector_receipt metadata;
• opaque external IDs only; no direct cross-service SQL;
• signed short-lived tenant/project/purpose claims;
• allowlisted endpoint, exact host/port, method, MIME, timeout, request/response size, redirect, and retry policy;
• upload/reference consent and data-classification review;
• conversion status, retry, cancellation, revocation, and artifact expiry;
• immutable source hash and project/snapshot/table binding;
• fixed non-reflecting failure responses and customer-facing next actions;
• no document contents in logs, metrics, billing, or generic LLM traces.

2. Grounded reversing specification

exact snapshot
+ authorized project references
→ evidence bundle
→ contextual-orchestrator operation
→ schema-bound draft
→ independent grounding verification
→ reviewed specification revision

Required behavior:

• replace direct LLM_API_BASE_URL/key/model runtime authority with a versioned orchestrator operation such as draft_database_reversing_spec;
• send bounded semantic evidence units, not unrestricted documents or DSNs;
• include snapshot hash, evidence IDs, model/provider identifiers, prompt hash, orchestration mode, reasoning effort, knowledge cutoff, and verification result;
• distinguish local deterministic draft, LLM draft, verified draft, and human-approved revision;
• use model discovery and compatible fallback across configured providers, including NVIDIA NIM, without assuming chat-completions semantics for every model;
• allocate test-time compute by workflow role; keep speed secondary to correctness for final verification;
• detect unsupported claims, wrong object names/cardinality, inverted relationships, fabricated rationale, and prompt injection from comments/documents;
• no automatic publication or migration approval from LLM output.

3. Naruon/context-fabric projection

Publish a read-only, versioned evidence contract for authorized consumers:

• canonical project/snapshot/object references;
• truth status (observed, declared, inferred, proposed);
• valid/system time and knowledge cutoff;
• provenance and source hashes;
• policy-filtered metadata with no DSN/secret;
• idempotent event/receipt contract;
• no requirement that naruon be present for standalone operation.

Required adversarial tests

• cross-tenant/project attachment and artifact-reference injection;
• connector credential revocation during an in-flight job;
• timeout, duplicate/reordered webhook/receipt, stale artifact, and provider partial failure;
• redirect/DNS-rebinding/oversized body/wrong MIME/host confusion;
• document prompt injection and schema comment injection;
• unsupported model capability and fallback across model classes;
• LLM output with fabricated table/column/FK and evidence ID;
• knowledge-cutoff leakage from a later snapshot/document;
• standalone mode with all connectors disabled;
• contract compatibility against pinned Clearfolio, contextual-orchestrator, and naruon fixtures;
• production statement/branch coverage 100% and public API docstrings 100%.

Acceptance evidence

• provider/consumer OpenAPI/AsyncAPI or equivalent versioned contracts and generated clients;
• ADRs for authority, tenancy, purpose, evidence, failure, and standalone/module boundaries;
• frontend Figma/Storybook states for unavailable, consent, processing, retry, expired, verified, unsupported, and access-denied paths;
• OpenTelemetry spans and connector SLOs without customer contents;
• real sandbox integration tests plus offline contract tests;
• exact-current-head required checks and independent review;
• docs/product-technical-gap-baseline.md, architecture, PRD/TRD, security/doctoring, and CHANGELOG updated.

References — APA 7th

Cloud Native Computing Foundation. (n.d.). CloudEvents specification. https://github.com/cloudevents/spec

World Wide Web Consortium. (2013). PROV-O: The PROV ontology. https://www.w3.org/TR/prov-o/

National Institute of Standards and Technology. (2024). Artificial intelligence risk management framework: Generative artificial intelligence profile (NIST AI 600-1). https://doi.org/10.6028/NIST.AI.600-1