From 472b7a8b30413827858baa3a2aa97b86e9507616 Mon Sep 17 00:00:00 2001 From: essius10 Date: Sat, 5 Sep 2026 22:13:47 +0530 Subject: [PATCH 1/2] docs: define ArchaeoAI commercial product vision --- docs/product/COMMERCIAL_MVP_REQUIREMENTS.md | 101 ++++++++++++++++++ docs/product/COMMERCIAL_PRODUCT_VISION.md | 77 +++++++++++++ .../PRODUCT_EVIDENCE_AND_HUMAN_REVIEW.md | 67 ++++++++++++ 3 files changed, 245 insertions(+) create mode 100644 docs/product/COMMERCIAL_MVP_REQUIREMENTS.md create mode 100644 docs/product/COMMERCIAL_PRODUCT_VISION.md create mode 100644 docs/product/PRODUCT_EVIDENCE_AND_HUMAN_REVIEW.md diff --git a/docs/product/COMMERCIAL_MVP_REQUIREMENTS.md b/docs/product/COMMERCIAL_MVP_REQUIREMENTS.md new file mode 100644 index 0000000..f9c3b19 --- /dev/null +++ b/docs/product/COMMERCIAL_MVP_REQUIREMENTS.md @@ -0,0 +1,101 @@ +# ArchaeoAI commercial MVP requirements + +## Status + +This document specifies a possible future MVP. It does not authorize implementation, model +execution, real-data ingestion, a pilot, Phase 5F, or public access. + +## Bounded user journey + +1. An authorized user creates a project with a defined purpose and accountable organization. +2. The user accepts applicable data, privacy, retention, and acceptable-use terms. +3. The user supplies terrain and project inputs they are authorized to process. +4. The system validates identity, permission, format, CRS, dimensions, resolution, size, and + content before admission. +5. The system creates an auditable processing contract and accepts or divides terrain only through + an explicitly approved tiling workflow. +6. The existing frozen terrain pipeline prepares the four representations and 4,096 features. +7. An approved model runtime may score patches only in an authorized deployment after artifact + identity, configuration, and state checks succeed. +8. The system records bounded `AI_OUTPUT` or `AI_HYPOTHESIS` results using controlled terminology. +9. Hypotheses enter a permissioned review queue without becoming archaeological determinations. +10. A qualified human examines selected terrain and supporting evidence. +11. Human observations and archaeological interpretations remain separately attributed from AI + output. +12. The system produces an auditable report containing scope, provenance, review state, and limits. +13. Sensitive inputs and derived data follow the project’s approved retention/deletion schedule. + +## Capability classification + +| Capability | Classification | Minimum requirement or reason | +| --- | --- | --- | +| Authentication | MVP REQUIRED | Strong individual identity; no anonymous processing. | +| Organization and project permissions | MVP REQUIRED | Least privilege with explicit project membership and reviewer roles. | +| Project workspace | MVP REQUIRED | Stable project purpose, owner, scope, status, and data-policy record. | +| Terms and authorization attestation | MVP REQUIRED | Record authority to process supplied data and accept handling conditions. | +| Authorized terrain ingestion | MVP REQUIRED | Controlled local import or private upload; strict type and size allowlist. | +| Raster validation | MVP REQUIRED | Preserve the Phase 5 canonical contract or use a separately approved preprocessing stage. | +| Bounded processing | MVP REQUIRED | Explicit quotas, isolation, deterministic job identity, and fail-closed admission. | +| Job status | MVP REQUIRED | Controlled states and error codes without paths, coordinates, or content leakage. | +| Approved model runtime | MVP REQUIRED for scored pilot | Disabled unless the private artifact, licence, deployment, and review gates pass. | +| Review queue | MVP REQUIRED | Permissioned, private, and clearly labelled as machine-generated hypotheses. | +| Human annotations | MVP REQUIRED | Authenticated author, timestamp, evidence level, rationale, and immutable history. | +| Evidence-level enforcement | MVP REQUIRED | Machines limited to Levels 1–2; higher transitions require appropriate humans. | +| Controlled output terminology | MVP REQUIRED | No discovery, probability, clearance, approval, or known-negative claims. | +| Report generation | MVP REQUIRED | Bounded report with provenance, AI/human separation, limitations, and audit references. | +| Audit history | MVP REQUIRED | Append-only security and decision events with sensitive-field minimization. | +| Retention and deletion | MVP REQUIRED | Project policy, expiry, verified deletion, legal-hold exception, and deletion evidence. | +| Export controls | MVP REQUIRED | Permissioned, reviewed exports; no public candidate-location export. | +| Multi-tenant managed SaaS | LATER | Requires a separate cross-tenant and public-service approval gate. | +| Automated reprojection/mosaicking | LATER | Must be an explicit, versioned preprocessing product with equivalence tests. | +| Integrations with HER/GIS/planning systems | LATER | Require source terms, authorization, field mapping, and leakage review. | +| Billing and payment | LATER | Commercial operations follow—not establish—workflow safety and demand. | +| Mobile field application | LATER | Requires location, offline-storage, and field-safety review. | +| Public API or public upload form | OUT OF SCOPE | Phase 5F is not authorized; anonymous location processing is unsafe. | +| Public candidate map or feed | OUT OF SCOPE | Conflicts with archaeological sensitivity and evidence boundaries. | +| Automatic archaeological decision or clearance | OUT OF SCOPE | Software must never make the final archaeological determination. | +| Automatic retraining or model substitution | OUT OF SCOPE | Would violate the frozen model and evidence boundary. | + +## Core screen concepts + +- **Projects:** only projects the authenticated user is permitted to access, with purpose, owner, + retention state, and review status. +- **New screening project:** controlled scope and authorization capture followed by bounded terrain + ingestion; no public map submission. +- **Processing:** safe job state, admitted/rejected counts, processing-contract identity, and fixed + errors without private paths or coordinates. +- **Screening results:** private terrain-pattern-similarity hypotheses and aggregate summaries; + never automatic “archaeological site” labels. +- **Review queue:** assigned human review with blinded or score-aware modes defined by protocol, + controlled categories, and explicit evidence level. +- **Evidence record:** immutable separation of machine output, human observation, qualified + archaeological interpretation, supporting sources, and any later confirmation. +- **Report:** permissioned preview/export of bounded findings, provenance, review status, and + limitations. +- **Project settings:** membership, roles, retention/deletion, export permissions, and audit access. + +These are information-architecture concepts, not frontend designs or implementation authorization. + +## Professional report concept + +A report should contain: + +1. project identifier, accountable organization, purpose, and authorized scope; +2. input description, rights attestation, CRS/resolution, and data provenance; +3. processing contract, software version, model/config identity, and integrity checks; +4. terrain and representation QA with admitted/rejected aggregate counts; +5. screening summary using terrain-pattern-similarity terminology; +6. AI-generated hypotheses with their evidence level and controlled limitations; +7. human-review state, reviewer identity/role, method, and separately attributed observations; +8. archaeological interpretation only when supplied and signed by a qualified reviewer; +9. unresolved limitations, excluded uses, and recommended next professional step; +10. retention/deletion status and an audit-record reference. + +The report must never translate a score into archaeological certainty, certify absence, grant +approval or clearance, or obscure whether qualified human review occurred. + +## Acceptance boundary + +An MVP is not credible merely because screens exist. Before use it must pass the Phase 6A decision +gates, threat/privacy testing, licensing review, model/IP decision, professional workflow review, +and a separately authorized bounded pilot. Phase 5E completion alone would not authorize it. diff --git a/docs/product/COMMERCIAL_PRODUCT_VISION.md b/docs/product/COMMERCIAL_PRODUCT_VISION.md new file mode 100644 index 0000000..9b040f3 --- /dev/null +++ b/docs/product/COMMERCIAL_PRODUCT_VISION.md @@ -0,0 +1,77 @@ +# ArchaeoAI commercial product vision + +## Status and boundary + +This is a Phase 6A design hypothesis, not a deployed product, public inference authorization, or +claim of validated demand. Phase 5E remains incomplete, Phase 5F remains unauthorized, and the +scientific status remains `RQ1_PROVISIONALLY_ANSWERED_PENDING_REVIEW`. + +## Problem + +Professional land and heritage work can require substantial manual review of terrain and related +evidence. A carefully bounded tool may help qualified teams prioritize terrain morphology for +review while preserving provenance, uncertainty, and human accountability. ArchaeoAI has not yet +demonstrated time savings, cost savings, customer demand, or suitability for a live professional +decision. + +## Proposed product + +**A controlled archaeological-terrain screening workspace that processes authorized terrain, +records bounded AI-generated terrain-pattern hypotheses, supports qualified human review, and +produces auditable project reports without presenting machine output as archaeological fact.** + +The smallest credible value proposition is review prioritization and traceability. The product +would help a professional organize a defined screening task; it would not make the final heritage, +planning, legal, or construction decision. + +## Non-goals + +- Automatic confirmation or rejection of archaeology. +- Replacement of archaeologists or professional judgement. +- Planning approval, legal heritage advice, or automatic construction clearance. +- England-wide archaeological certainty or transfer beyond the bounded E001 evidence. +- A public candidate map, location feed, or discovery engine. +- A calibrated “chance that archaeology exists” or an archaeology-free determination. +- Unsupervised scanning of land without lawful authority and a defined project purpose. + +## Likely user groups—not confirmed customers + +| Possible user | Job to be done | Information supplied | Needed output | Expertise still required | +| --- | --- | --- | --- | --- | +| Archaeological consultancy | Prioritize terrain review within an authorized project area. | Project boundary, authorized DTM, project context, review policy. | Traceable screening queue and bounded report. | Qualified archaeological interpretation and follow-up design. | +| Environmental or heritage consultancy | Integrate terrain screening into a wider evidence assessment. | Authorized terrain, scope, constraints, existing desk-study context. | Auditable hypotheses and limitations for expert review. | Heritage assessment, source reconciliation, and professional sign-off. | +| Infrastructure project team | Commission a defined, reviewable terrain-screening task. | Project authority, data rights, area and purpose. | Status, provenance, review trail, and professional report. | Archaeological consultant oversight and statutory-process advice. | +| Renewable-energy project team | Identify terrain requiring early specialist attention. | Authorized project data and screening brief. | Prioritized expert-review workflow, not clearance. | Archaeologist assessment and planning/legal judgement. | +| Planning or land-development team | Support early evidence gathering without treating absence as clearance. | Authorized terrain, project scope, access permissions. | Bounded screening summary with unresolved risks. | Qualified heritage advice and formal decision-making. | +| Qualified archaeological professional | Review machine-generated terrain hypotheses consistently. | Review credentials, annotations, supporting evidence. | Separated AI/human evidence record and auditable report. | Domain interpretation, fieldwork recommendations, and accountable conclusions. | + +These are discovery hypotheses for future interviews. They are not customers, endorsements, or +evidence of product-market fit. + +## Product principles + +1. **Human authority:** software can organize and score terrain patterns but cannot make an + archaeological determination. +2. **Evidence separation:** AI output, AI hypothesis, human observation, archaeological + interpretation, and confirmed evidence remain distinct records. +3. **Private by default:** locations and location-linked material remain within the authorized + project boundary and are never public by default. +4. **Reuse, do not fork:** future product processing must call the verified Phase 5 contracts rather + than create a second commercial feature path. +5. **Fail closed:** ambiguous inputs, artifacts, permissions, or evidence states stop processing. +6. **Auditable limits:** every report identifies the processing contract, model/config identity, + human-review state, provenance, and limitations. + +## Business-model hypotheses + +Possible future models include a paid professional pilot, per-project analysis, an annual +professional licence, a controlled private deployment, or an enterprise contract. No price, +revenue, customer, or product-market-fit claim is made. Commercial validation requires separate, +documented customer discovery and cannot be inferred from technical or scientific results. + +## Success for a future pilot + +A pilot would be successful only if authorized professional users find the workflow useful and +auditable, reviewers can preserve the evidence boundary, security/privacy controls pass the +required gates, and limitations remain visible. Predictive scores alone cannot establish product +success or professional acceptability. diff --git a/docs/product/PRODUCT_EVIDENCE_AND_HUMAN_REVIEW.md b/docs/product/PRODUCT_EVIDENCE_AND_HUMAN_REVIEW.md new file mode 100644 index 0000000..66a218d --- /dev/null +++ b/docs/product/PRODUCT_EVIDENCE_AND_HUMAN_REVIEW.md @@ -0,0 +1,67 @@ +# Product evidence and human review + +## Controlling rule + +The product must store evidence provenance and level explicitly. A machine may create only Levels +1–2. No score, threshold, rank, label, interface action, or report template may automatically +promote evidence to a human or archaeological level. + +## Evidence ladder + +| Level | Record | Created by | Minimum evidence | Permitted transition | +| ---:| --- | --- | --- | --- | +| 1 | `AI_OUTPUT` | Approved software runtime | Validated input, verified processing/model identity, raw bounded machine result, and audit event. | Software may propose Level 2 with explicit hypothesis wording; a human may retain, reject, or annotate it. | +| 2 | `AI_HYPOTHESIS` | Approved software under a frozen rule, or an authenticated human reframing Level 1 | Level 1 provenance plus a testable terrain-morphology hypothesis and mandatory limitations. | Requires human examination to reach Level 3; cannot skip levels automatically. | +| 3 | `HUMAN_VETTED_OBSERVATION` | Authenticated human reviewer | Reviewed source material, recorded method/category/rationale, date, identity, and conflicts/limitations. | Requires appropriate archaeological expertise and separate interpretation to reach Level 4. | +| 4 | `ARCHAEOLOGIST_VALIDATED_INTERPRETATION` | Authenticated, suitably qualified archaeological professional | Levels 1–3 provenance where relevant, relevant contextual evidence, professional rationale, attribution, and limitations. | Confirmation at Level 5 requires appropriate independent corroboration; software cannot perform it. | +| 5 | `CONFIRMED_ARCHAEOLOGICAL_EVIDENCE` | Authorized professional/institutional process, not the model | Corroboration appropriate to context, such as verified records, field investigation, or other accepted evidence, with accountable documentation. | Terminal evidence classification for this ladder; it does not imply planning approval or unrestricted publication. | + +## Human and expertise transitions + +- Level 1 → Level 2 may be deterministic software framing, but the record remains automatic and + must say `AI_HYPOTHESIS`. +- Level 2 → Level 3 requires an authenticated human review action and a recorded rationale. +- Level 3 → Level 4 requires a suitably qualified archaeological professional acting within the + project’s authorized scope. +- Level 4 → Level 5 requires appropriate corroboration and accountable professional or + institutional confirmation; a visual terrain judgement alone is insufficient. +- Rejection, uncertainty, and “insufficient evidence” are first-class review outcomes. The system + must not pressure reviewers to promote an item. + +## Software prohibitions + +The software must never automatically: + +- create Levels 3–5 or imply that those reviews occurred; +- label a location an archaeological site, discovery, known negative, or safe area; +- interpret a score as archaeological probability or certainty; +- infer reviewer credentials, endorsement, consensus, or independence; +- overwrite machine provenance with a human label or merge distinct evidence records; +- use human annotations, candidate review, or the spent external test for retraining without a new + scientific protocol and independent evaluation; +- publish candidate locations or promote them into public reports. + +## Review record requirements + +Every human action should record reviewer identity, role and claimed expertise, timestamp, material +reviewed, whether score/rank was visible, controlled category, notes, evidence level before/after, +supporting evidence references, conflicts/limitations, and supersession history. Corrections append +a new event; they do not erase the original record. + +Review assignment and access must follow project permissions. A report may summarize the review +state only from attributed records and must identify unreviewed or disputed items explicitly. + +## Product terminology + +Preferred terms are **archaeological terrain screening**, **terrain-pattern similarity**, +**candidate terrain morphology**, **review prioritization**, **AI-generated hypothesis**, and +**human review required**. Model output is not an archaeological probability, discovery, planning +decision, construction clearance, or finding that no archaeology is present. + +## Current research boundary + +The existing Phase 2F packet remains privately prepared but unreviewed; it is not a product review +queue or evidence of Levels 3–5. E001 remains limited to documented bowl-barrow terrain versus +matched `unlabelled_background` under the evaluated geographic design. This product ladder does +not change any scientific result or the status +`RQ1_PROVISIONALLY_ANSWERED_PENDING_REVIEW`. From 6b030feb3784ea5171cc2318b20b394ffbbb5b38 Mon Sep 17 00:00:00 2001 From: essius10 Date: Sat, 5 Sep 2026 22:16:25 +0530 Subject: [PATCH 2/2] docs: add commercial architecture and safety gates --- docs/product/COMMERCIAL_DECISION_GATES.md | 88 ++++++++++++++ docs/product/COMMERCIAL_OPEN_QUESTIONS.md | 51 ++++++++ .../product/COMMERCIAL_SYSTEM_ARCHITECTURE.md | 112 ++++++++++++++++++ docs/product/COMMERCIAL_THREAT_MODEL.md | 47 ++++++++ .../PRODUCT_PRIVACY_AND_DATA_LIFECYCLE.md | 74 ++++++++++++ 5 files changed, 372 insertions(+) create mode 100644 docs/product/COMMERCIAL_DECISION_GATES.md create mode 100644 docs/product/COMMERCIAL_OPEN_QUESTIONS.md create mode 100644 docs/product/COMMERCIAL_SYSTEM_ARCHITECTURE.md create mode 100644 docs/product/COMMERCIAL_THREAT_MODEL.md create mode 100644 docs/product/PRODUCT_PRIVACY_AND_DATA_LIFECYCLE.md diff --git a/docs/product/COMMERCIAL_DECISION_GATES.md b/docs/product/COMMERCIAL_DECISION_GATES.md new file mode 100644 index 0000000..3c62174 --- /dev/null +++ b/docs/product/COMMERCIAL_DECISION_GATES.md @@ -0,0 +1,88 @@ +# ArchaeoAI commercial decision gates + +## Rule + +Every gate starts **NOT COMPLETED**. Evidence and an accountable decision must be recorded; absence +of a concern is not approval. A gate may be `GO`, `GO WITH CONDITIONS`, or `NO-GO`. A later gate +cannot override an unresolved blocker in an earlier gate. + +## Gate A — Scientific integrity + +Confirm claims remain limited to E001’s documented bowl-barrow terrain versus matched +`unlabelled_background`, evaluated geographies, and stated uncertainty. Scores remain terrain- +pattern similarity, not archaeological probability. No discovery, absence, clearance, universal +generalization, or automatic professional determination is implied. + +**Minimum evidence:** claims-register audit, frozen-artifact diff, terminology review, and +documented confirmation that the spent external test was not reused. + +## Gate B — Phase 5E review + +Appropriate external reviewers examine security, privacy, archaeological/scientific workflow, and +licensing/data/model issues using the Phase 5E checklist. Substantive findings receive documented +resolution or an explicitly accepted residual risk appropriate to the intended deployment. + +**Current state:** **NOT COMPLETED.** Phase 6A does not complete it or authorize Phase 5F. + +## Gate C — Data licensing + +Verify commercial-use, hosting, transformation, derived-output, attribution, redistribution, and +deletion rights for every proposed data source and customer-supplied input. Resolve jurisdiction, +contract, and source-version differences. + +**Stop if:** a required right or attribution obligation is unclear or incompatible. + +## Gate D — Model/IP + +Establish ownership, authority to use commercially, distribution restrictions, approved runtime +location, artifact format, provenance, integrity/state verification, and protection/support policy. + +**Stop if:** ownership or redistribution/runtime authority is unclear, or safe loading cannot be +demonstrated. + +## Gate E — Real-input authorization + +For any pilot, record project purpose, data provider, rights/consent, geographic scope, responsible +organization, privacy/retention terms, and ethical authority before admission. + +**Stop if:** authorization is missing, overly broad, unverifiable, or conflicts with archaeological +sensitivity. + +## Gate F — Professional workflow review + +At least one appropriate external domain professional reviews the intended user journey, +terminology, evidence ladder, review burden, report, and escalation process. Their role, scope, +conflicts, limitations, findings, and dispositions must be recorded without implying endorsement. + +**Current state:** no completion is claimed by this design. + +## Gate G — Pilot authorization + +Only after Gates A–F are sufficiently resolved may the owner separately authorize a bounded pilot. +The decision must name the deployment, organization, users, inputs, model, limits, monitoring, +retention, support, stop conditions, and success criteria. A pilot is not general release. + +## Gate H — Public/SaaS decision + +A local/private pilot does not authorize public SaaS. Internet access, uploads, multitenancy, +central storage, telemetry, public interfaces, scaling, incident response, and abuse controls need +a separate architecture, threat/privacy review, professional review, and explicit owner approval. + +## Decision record template + +- Gate and date: +- Decision: `GO` / `GO WITH CONDITIONS` / `NO-GO` +- Accountable owner: +- Reviewers and scope (no endorsement implied): +- Evidence reviewed: +- Findings and unresolved risks: +- Required actions, owners, and deadlines: +- Deployment or activity explicitly authorized: +- Activities explicitly not authorized: +- Re-review trigger: + +## Current authorization boundary + +Phase 6A authorizes documentation and architecture discussion only. It authorizes no model loading, +real terrain processing, customer-data storage, pilot, Phase 5F work, public interface, deployment, +commercial claim, or candidate publication. diff --git a/docs/product/COMMERCIAL_OPEN_QUESTIONS.md b/docs/product/COMMERCIAL_OPEN_QUESTIONS.md new file mode 100644 index 0000000..6d84b45 --- /dev/null +++ b/docs/product/COMMERCIAL_OPEN_QUESTIONS.md @@ -0,0 +1,51 @@ +# ArchaeoAI commercial open questions + +## Status + +This is a prioritized register of unresolved questions, not a set of assumed answers. `BLOCKER` +means the issue must be resolved for the relevant pilot or deployment; `IMPORTANT` means it should +shape design and approval; `LATER` means it is intentionally deferred beyond the first bounded +pilot. + +| Category | Severity | Question | Why it matters | Owner/reviewer type needed | +| --- | --- | --- | --- | --- | +| Scientific | BLOCKER | What claims and use cases remain defensible when E001 covers one narrow class and bounded geographies? | Product wording and safe decisions cannot exceed evidence. | Research lead, statistician, archaeologist. | +| Scientific | IMPORTANT | What independent evidence would be required before evaluating another class, terrain source, or geography? | Prevents product pressure from becoming unregistered model expansion. | Research methodologist and archaeologist. | +| Archaeological | BLOCKER | Which screening decisions may the tool support, and which must remain solely professional? | Defines safe workflow, liability, and evidence transitions. | Qualified archaeological professional and legal adviser. | +| Archaeological | BLOCKER | What reviewer qualifications and corroboration are required for Levels 3–5? | Prevents software or unqualified review from implying validation. | Professional archaeology body/practitioner. | +| Archaeological | IMPORTANT | How should sensitive candidate locations be handled across clients, reports, regulators, and archives? | Disclosure may create heritage harm or breach obligations. | Archaeologist, data protection/privacy lead, client. | +| Product | BLOCKER | Which single professional job is valuable enough for a bounded pilot without implying automated determination? | A credible MVP needs a narrow user outcome. | Product researcher and prospective professional users. | +| Product | IMPORTANT | What evidence and interface context do reviewers need without anchoring them improperly to scores? | Review design affects bias, burden, and usefulness. | UX researcher, archaeologist, research methodologist. | +| Product | IMPORTANT | What pilot success criteria measure workflow value, safety, and auditability without reusing scientific tests? | Prevents metrics from overstating product or model performance. | Product owner, research lead, pilot partner. | +| Security | BLOCKER | Can untrusted raster processing be isolated and resource-bounded under the chosen deployment? | File parsing is a primary attack surface. | Security engineer and platform engineer. | +| Security | BLOCKER | Can the approved model be loaded without accepting arbitrary pickle risk or exposing the artifact? | Unsafe deserialization can compromise the host and model IP. | ML security engineer and model owner. | +| Security | IMPORTANT | What identity, authorization, support-access, and incident controls are proportionate for a private pilot? | Sensitive projects require accountable access. | Security architect and deployment operator. | +| Privacy | BLOCKER | What exact retention/deletion schedule applies to every sensitive data class, backups, and reports? | “Minimum retention” must become enforceable behavior. | Privacy/legal adviser, archaeologist, client records owner. | +| Privacy | BLOCKER | What lawful basis, notices, contracts, and jurisdiction apply to client terrain and location data? | Processing cannot begin without clear authority and obligations. | Data protection/legal adviser and client. | +| Privacy | IMPORTANT | Are any aggregated telemetry fields safe and genuinely necessary? | Operational visibility can accidentally disclose location or activity. | Privacy engineer and security reviewer. | +| Licensing | BLOCKER | Do all source terms permit the intended commercial processing, hosting, derived outputs, and client reporting? | Research permissions do not automatically establish commercial rights. | Licensing/legal specialist and data providers. | +| Licensing | IMPORTANT | What attribution and redistribution language must appear in reports and exports? | Deliverables must preserve source obligations. | Licensing specialist and report owner. | +| Model/IP | BLOCKER | Who owns the trained artifact and has authority to use, distribute, host, modify, and support it commercially? | The current private artifact cannot be assumed deployable. | Repository/model owner and IP counsel. | +| Model/IP | BLOCKER | Is a safer portable model format technically equivalent and legally acceptable? | Hash-bound pickle has code-execution risk; conversion could change outputs. | ML engineer, security engineer, research lead. | +| Infrastructure | BLOCKER | What local/private packaging and update mechanism preserves reproducibility, signatures, and rollback? | First deployment must be supportable without silent drift. | Platform engineer and security/reproducibility reviewer. | +| Infrastructure | IMPORTANT | How are append-only audit records and verified deletion implemented, including backups? | Accountability and privacy require both history and controlled erasure. | Platform engineer, security/privacy leads. | +| Infrastructure | LATER | What tenancy, regional hosting, availability, and disaster-recovery design would SaaS require? | These matter only after a separate public/SaaS decision. | Cloud architect, security/privacy/legal leads. | +| Business | BLOCKER | Will professional organizations participate in a bounded, paid or unpaid discovery/pilot process? | Technical readiness does not demonstrate demand. | Founder/product researcher and prospective users. | +| Business | IMPORTANT | Which delivery hypothesis—pilot, per-project, annual licence, private deployment, or enterprise contract—best fits procurement and risk? | Determines operations and product constraints; no price is assumed. | Business lead, procurement stakeholders, legal adviser. | +| Business | LATER | What pricing, support, insurance, and service-level model is viable? | These require real discovery and cost evidence. | Business/finance/legal leads. | +| Customer validation | BLOCKER | Do independent professionals understand and accept the terminology, evidence ladder, limitations, and required human work? | Misunderstanding would create unsafe reliance. | External archaeologists and consultancy users. | +| Customer validation | BLOCKER | Does the workflow improve prioritization or auditability in a real authorized project without displacing required review? | Core value remains unvalidated. | Pilot partner, independent evaluator, product researcher. | +| Customer validation | IMPORTANT | What objections, integration needs, and adoption barriers recur across different organization types? | Prevents designing from untested assumptions. | Product researcher and diverse prospective users. | + +## Highest-priority blockers + +The first five questions to resolve are: + +1. the defensible professional use and claim boundary for narrow E001 evidence; +2. commercial source-data and derived-output rights; +3. model ownership, runtime authority, and safe artifact format; +4. enforceable security isolation and privacy retention/deletion for authorized inputs; +5. external professional acceptance of the human-review workflow and evidence ladder. + +No blocker is resolved by repository documentation alone. Answers require attributable evidence and +must be carried into the corresponding commercial decision-gate record. diff --git a/docs/product/COMMERCIAL_SYSTEM_ARCHITECTURE.md b/docs/product/COMMERCIAL_SYSTEM_ARCHITECTURE.md new file mode 100644 index 0000000..9da34e3 --- /dev/null +++ b/docs/product/COMMERCIAL_SYSTEM_ARCHITECTURE.md @@ -0,0 +1,112 @@ +# ArchaeoAI commercial system architecture + +## Status and recommendation + +This is a hypothetical Phase 6A architecture, not implementation or deployment authorization. +The recommended first deployment model is a **controlled local/private professional deployment** +inside an owner-approved environment. A managed cloud SaaS should remain a separate later decision +because sensitive locations, model protection, tenancy, uploads, and retention substantially +increase risk. + +## Architectural rule: one inference path + +The future product must orchestrate—not replace—the Phase 5 contracts: + +```text +authorized input +→ Phase 5 input validation +→ frozen preprocessing and 4,096-feature contract +→ approved hash-bound model boundary (only when separately authorized) +→ safe result contract +→ evidence ladder +→ bounded batch primitives +→ authenticated human review and report +``` + +No “commercial” preprocessing, scoring, serializer, or evidence shortcut may run in parallel with +this path. Any new tiling, reprojection, model-loading, or persistence layer must sit outside the +canonical core, produce an auditable versioned input, and pass equivalence and privacy review. + +## Logical components + +| Component | Responsibility | Trust boundary | +| --- | --- | --- | +| Professional client | Project, authorization, upload/import, review, report, deletion controls. | Shows only projects and data permitted to the authenticated user. | +| Authenticated API or local service | Validates identity, role, project state, request schema, quotas, and idempotency. | No anonymous or cross-project access; no public inference endpoint. | +| Project metadata service | Stores purpose, organization, permissions, data-policy state, and workflow status. | Excludes terrain values and precise locations from ordinary metadata/logs. | +| Secure object storage | Holds authorized terrain and approved derived private material. | Project-scoped encryption, short-lived access, no public ACL, lifecycle deletion. | +| Job queue | Carries opaque project/job references and controlled states. | No paths, coordinates, feature vectors, scores, or raster bytes in messages. | +| Isolated terrain worker | Performs explicit preprocessing then calls the exact Phase 5 validation/feature path. | Sandboxed, resource-limited, minimal filesystem, no outbound network by default. | +| Isolated model runtime | Verifies approved artifact/config/state and scores canonical feature matrices. | Separate authorization; no pickle from users, retraining, fallback model, or internet download. | +| Results database | Stores private machine evidence, controlled status, and links to project-scoped geometry. | Row/project authorization; sensitive columns never exposed by generic queries. | +| Human-review application | Records assignments, blinded state, annotations, expertise, and evidence transitions. | Machine output cannot impersonate or promote a reviewer. | +| Report generator | Produces bounded, permissioned reports from verified records and templates. | No automatic certainty, clearance, discovery, or public candidate publication. | +| Append-only audit log | Records security and decision events with actor, time, object, action, and version. | Sensitive values minimized or tokenized; access itself is audited. | +| Retention/deletion service | Applies expiry, deletion, legal holds, and deletion evidence across stores/backups. | Failures alert owners; deletion is verified rather than assumed. | + +In a local/private deployment these may be packaged into fewer processes, but the trust boundaries, +separate evidence records, least privilege, and audit requirements remain. + +## Option A — Local/private professional deployment + +| Dimension | Assessment | +| --- | --- | +| Security | Smaller exposed surface and easier network isolation; endpoint hardening and update discipline remain necessary. | +| Privacy/sensitive archaeology | Terrain and candidate locations can remain within the professional organization’s controlled environment. | +| Deployment complexity | Installation, hardware compatibility, upgrades, backups, and support must be standardized. | +| Maintenance | More version fragmentation; signed packages, supported versions, and upgrade evidence are required. | +| Model protection | Artifact can be delivered through a controlled channel and kept local, though a customer administrator may access it. | +| Customer usability | Lower upload burden and compatible with private workflows; setup may be less convenient than SaaS. | +| Auditability | Local append-only records and exportable signed reports are feasible; centralized visibility is limited. | +| Cost | Avoids permanent hosted infrastructure but creates installation and support cost; no cost claim is validated. | +| Scalability | Suitable for bounded professional pilots; constrained by local hardware and operational maturity. | + +## Option B — Managed cloud SaaS + +| Dimension | Assessment | +| --- | --- | +| Security | Adds internet exposure, authentication, tenant isolation, object storage, API abuse, secrets, and incident-response obligations. | +| Privacy/sensitive archaeology | Uploads and centralized candidate locations increase breach and jurisdiction risk. | +| Deployment complexity | Easier client access but materially harder secure platform engineering and compliance. | +| Maintenance | Centralized updates and observability are simpler, subject to safe telemetry and change control. | +| Model protection | Server-side runtime can limit artifact distribution, but infrastructure compromise could expose it. | +| Customer usability | Browser workflow may be easier if upload size, bandwidth, GIS interoperability, and trust are solved. | +| Auditability | Central policy enforcement is possible, but cross-tenant logs and support access require strong controls. | +| Cost | Ongoing compute, storage, egress, security, and support costs; no commercial estimate is established. | +| Scalability | Potentially greater, but only after quotas, isolation, scheduling, and operational controls are validated. | + +## First-deployment conclusion + +Begin, if later gates authorize it, with a single-organization local/private pilot: bounded projects, +named users, private storage, no public endpoint, no anonymous upload, and explicit deletion. This +reduces—not eliminates—risk and provides a setting for professional workflow evaluation. Success +would not authorize public SaaS; Option B requires a separate Gate H decision. + +## Control and data flows + +1. A project owner establishes purpose, access, data rights, retention, and reviewer roles. +2. Admission validates authorization before file parsing and applies byte/item quotas. +3. Untrusted raster parsing occurs in an isolated, resource-limited worker. +4. Accepted canonical patches use the exact Phase 5 transformation; derived features remain + private and ephemeral unless a separately approved need is documented. +5. The model runtime remains disabled until the artifact/IP and deployment gates pass. When + enabled, it accepts only canonical feature matrices and emits bounded Level 1 results. +6. Private results enter a project-scoped review queue. Human records are appended separately. +7. Reports are rendered from allowlisted fields, carry limitations, and are access-controlled. +8. Retention expiry removes inputs and derived sensitive data across stores and records evidence. + +## Existing website reuse assessment + +The static `website/` can later inform visual language, research explanations, geographic- +validation education, aggregate figures, and responsible-archaeology wording. It is a research-only +communication artifact today. Its private-run section reports only coordinate-safe aggregate +evidence and must not become a candidate browser, upload form, authentication shell, score viewer, +commercial promise, or model-backed inference interface without separate approval. Phase 6A makes +no website change and authorizes no deployment. + +## Unresolved implementation decisions + +Identity provider, authorization model, storage technology, worker sandbox, deployment packaging, +artifact format, audit immutability, backup deletion, report signing, and operational ownership are +intentionally undecided. They follow the decision gates and external review; they are not selected +by this architecture sketch. diff --git a/docs/product/COMMERCIAL_THREAT_MODEL.md b/docs/product/COMMERCIAL_THREAT_MODEL.md new file mode 100644 index 0000000..92b8851 --- /dev/null +++ b/docs/product/COMMERCIAL_THREAT_MODEL.md @@ -0,0 +1,47 @@ +# ArchaeoAI preliminary commercial threat model + +## Scope and status + +This threat model identifies design risks for a possible professional product. It is not an +independent security assessment, penetration test, compliance claim, or deployment authorization. +Controls require validation before implementation and again before any pilot. + +| Threat | Potential impact | Proposed control | Required validation/review before implementation | +| --- | --- | --- | --- | +| Malicious uploads | Parser compromise, data exposure, resource exhaustion. | Authenticate first; strict extension/MIME/magic allowlist; byte quotas; quarantine; isolated parsing. | Adversarial upload tests, sandbox review, incident procedure. | +| Malformed GeoTIFFs | Crash, unsafe parser behavior, misleading processing. | Preserve canonical fail-closed Phase 5 validation; patched Rasterio/GDAL; isolate process. | Fuzz corpus, dependency review, malformed-file regression tests. | +| Raster decompression/resource attack | Excess CPU, memory, disk, or service denial. | Inspect metadata before decode; dimension/band/compression limits; worker memory/CPU/time/disk quotas. | Decompression-bomb tests and measured worst-case limits. | +| Path traversal | Read/write outside project storage. | Server-generated object keys; no caller filesystem paths; Phase 5 containment and allowlists. | Traversal, encoding, platform-path, and archive tests. | +| Symlink or link attack | Escape workspace or substitute content. | Reject links; isolated non-shared workspace; recheck identity/hash immediately before use. | Race/link tests on supported filesystems. | +| Cross-tenant access | Exposure of terrain, locations, reports, or annotations. | Prefer single-organization first deployment; project-scoped authorization and encryption keys. | Tenant-boundary tests and independent authorization review before SaaS. | +| IDOR/broken authorization | User accesses another project by changing an identifier. | Deny-by-default object authorization on every request; opaque IDs are not authorization. | Role matrix, negative API tests, review of every object endpoint. | +| Data or coordinate leakage | Sensitive archaeology/project location becomes visible. | Separate spatial data; output allowlists; redacted errors; no coordinates in logs/analytics. | Privacy tests, tracked-file scan, report/export review. | +| Log/telemetry leakage | Persistent sensitive metadata in third-party or support systems. | Structured controlled events; field allowlist; analytics off by default; short retention. | Log-schema tests and processor/subprocessor privacy review. | +| Object-storage exposure | Public bucket/link reveals source or results. | Block public access; least-privilege service identities; short-lived scoped URLs; encryption. | Cloud/local configuration audit and access probes. | +| Report leakage | Confidential hypotheses or locations reach an unauthorized recipient. | Project permissions, sensitivity labels, preview, export audit, expiring delivery. | Report red-team review and recipient/access tests. | +| Model theft or substitution | IP loss, malicious scoring, invalid evidence. | Isolated runtime; controlled distribution; signed/hash-bound artifact/config/state; no download fallback. | Ownership/licence decision, artifact-chain review, tamper tests. | +| Malicious pickle/model loading | Arbitrary code execution. | Never accept user models; verify approved provenance before hash; prefer safer format if validated; isolated loader. | Serialization-format decision, code-execution threat test, independent security review. | +| Dependency compromise | Compromised parser/runtime or build artifact. | Locked dependencies, hashes/signatures, SBOM, minimal image, vulnerability/change monitoring. | Supply-chain review, clean reproducible build, update policy. | +| Prompt injection if an LLM is introduced | Untrusted text changes workflow, leaks data, or fabricates claims. | No LLM in decision path by default; isolate untrusted text; strict tools/output schema; no secret/data access. | Separate LLM threat model, adversarial evaluation, explicit owner gate. | +| Privilege escalation | Worker or user gains host/admin access. | Non-admin services, sandboxing, capability reduction, secrets isolation, patched host. | Host/container hardening review and penetration test. | +| Abusive large jobs | Denial of service or unexpected cost. | Preserve 64-item primitive; project quotas; admission control; sequential/bounded jobs; cancellation. | Load/abuse tests and cost/resource alarms. | +| Queue/retry replay | Duplicate reports, scoring, or retention beyond policy. | Idempotency keys, immutable job state machine, bounded retries, duplicate-content controls. | Failure/recovery and concurrent-state tests. | +| Unauthorized candidate scraping | Systematic extraction of sensitive ranked locations. | No public endpoint/map; role-limited views; pagination/export caps; access anomaly review. | Abuse-case review and enumeration tests. | +| Public exposure of sensitive archaeology | Harm to sites and violation of professional obligations. | Private-by-default outputs; sensitivity review; prohibit public candidate publishing. | Archaeological professional and privacy approval for every publication class. | +| Insider/support misuse | Authorized account accesses data without project need. | Least privilege, just-in-time support access, dual approval for sensitive exports, audit alerts. | Operational access review and tabletop exercise. | +| Credential/session compromise | Unauthorized project and report access. | Strong identity, MFA, short sessions, secure recovery, revocation, device/session visibility. | Authentication design review and session security tests. | +| Deletion failure | Data persists in cache, backup, queue, or failed workspace. | Data inventory, lifecycle jobs, verified cleanup, backup-expiry policy, deletion audit. | End-to-end deletion and restore-path tests. | + +## Abuse controls + +A future service needs named users, acceptable-use terms, project-purpose recording, authorization +attestation, request and storage quotas, concurrent-job limits, controlled export, anomaly handling, +account suspension, and a private incident channel. These controls do not permit public or +unbounded scanning and must not rely on secrecy of identifiers. + +## Trust assumptions to challenge + +The first design assumes an owner-approved model, lawfully supplied terrain, an authenticated +professional organization, qualified reviewers, a patched trusted runtime, and a deployment +operator capable of enforcing deletion. Each assumption needs evidence at the applicable decision +gate. Failure or ambiguity is a stop condition, not a reason to silently degrade controls. diff --git a/docs/product/PRODUCT_PRIVACY_AND_DATA_LIFECYCLE.md b/docs/product/PRODUCT_PRIVACY_AND_DATA_LIFECYCLE.md new file mode 100644 index 0000000..0e677e1 --- /dev/null +++ b/docs/product/PRODUCT_PRIVACY_AND_DATA_LIFECYCLE.md @@ -0,0 +1,74 @@ +# Product privacy and data lifecycle + +## Default policy + +Collect the minimum data needed for a defined, authorized project; keep precise locations and +location-linked material private; exclude them from ordinary logs and analytics; apply short, +explicit retention; and publish no candidate location. This proposal requires privacy, legal, and +archaeological review before implementation. + +## Lifecycle + +```text +authorized input → validation → isolated processing → private derived data +→ permissioned review → bounded report → verified retention/deletion action +``` + +Validation failure should minimize retained content. Processing must not create undocumented +copies. Review and reporting must preserve machine/human provenance. Project closure triggers the +approved deletion schedule unless a documented legal hold applies. + +## Data classification and proposed handling + +“Project-private” means encrypted storage scoped to one authorized project. “Runtime-only” means +memory or a controlled workspace deleted at job completion. Exact durations are blockers for legal, +customer, and operational review; “project term” is not permission for indefinite retention. + +| Data class | Sensitivity | Needed? | Proposed location | Proposed retention | Logs | Analytics | Public output | +| --- | --- | ---:| --- | --- | --- | --- | --- | +| Project metadata | Internal/confidential | Yes | Project-private metadata store | Project term plus agreed short closure period | Opaque IDs/status only | De-identified operational counts only, with consent | No, unless owner approves non-sensitive summary | +| Terrain raster | Highly sensitive, location-linked | Yes | Local/private encrypted object store or runtime-only | Minimum processing/review period; delete on schedule | Never | Never | Never | +| Coordinates | Highly sensitive archaeological/project data | Often | Separate project-private spatial store | Minimum review/report need | Never | Never | Never by default | +| Bounds/transforms | Highly sensitive, reversible location data | Processing only | Runtime-only or protected spatial store | Job duration unless review need is approved | Never | Never | Never | +| Derived terrain products | Highly sensitive, location-linked | Sometimes | Runtime-only by default; project-private if review requires | Short review period | Never | Never | Never | +| Feature vectors | Sensitive derived model input | Transiently | Runtime-only | Delete after scoring unless a justified audit requirement exists | Never | Never | Never | +| AI scores | Sensitive project result | Yes for review | Results store separated from public reporting | Project/report lifecycle, then delete or restricted archive | Never | Aggregate service health only; no location linkage | Aggregate only if approved | +| Candidate locations | Highest sensitivity | Yes for review | Separate project-private spatial store | Minimum professional-review need | Never | Never | Never by default | +| Reviewer annotations | Confidential professional evidence | Yes | Project-private evidence store | Report/audit period under agreed policy | Event type only | De-identified workflow counts only if approved | Only bounded attributed report content with permission | +| Final report | Confidential deliverable | Yes | Project-private document store and authorized recipient copy | Contractual/professional record period | Access event only | Never use content | Only with explicit owner/client and sensitivity approval | +| Model artifact | Restricted IP/security asset | Yes only in authorized scored deployment | Isolated runtime or controlled local installation | Supported deployment life; revoke obsolete versions | Digest/version only | Version counts only | Never | +| Audit records | Security/professional record; metadata-sensitive | Yes | Append-only access-controlled store | Defined compliance/contract period | This is the controlled log | Aggregate operational metrics only | Bounded audit excerpt only with authorization | + +## Logging and analytics rules + +Logs may contain authenticated actor token, opaque project/job ID, controlled event/error code, +software/model version, timestamps, and bounded resource counts where justified. They must exclude +coordinates, bounds, transforms, paths, filenames, raster metadata, feature values, scores, +candidate IDs reversible to location, annotation text, report contents, and credentials. + +Analytics are off by default for a first private pilot. Any later analytics require purpose, +consent/legal basis, data minimization, aggregation thresholds, retention, access, and opt-out +review. Debug mode must not weaken the privacy boundary. + +## Retention and deletion requirements + +- Select and display a project policy before input admission; do not rely on an implicit default. +- Support early owner-requested deletion, scheduled expiry, and separately authorized legal holds. +- Delete primary objects, derived products, indexes, caches, temporary workspaces, queues, and + eligible backups; document unavoidable backup expiry. +- Record deletion evidence without retaining deleted sensitive values. +- Revoke links, credentials, and worker access when a project closes. +- Test interrupted jobs, partial failures, support access, exports, and restoration paths. + +## Public and export boundary + +No public candidate-location publication is allowed. Exports require role authorization, an +explicit content preview, controlled terminology, sensitivity marking, and an audit event. Reports +must distinguish AI and human evidence and cannot transform a score into archaeological fact. + +## Incident and subject handling + +Before a pilot, define breach triage, owner/client notification, credential revocation, evidence +preservation, and archaeological-sensitivity escalation. Also define who can request access, +correction, export, or deletion and how conflicting professional-record obligations are resolved. +These are open governance requirements, not claims of current compliance.