first commit

2026-07-11 14:56:10 +08:00
commit 7e05d0a4e7
660 changed files with 78119 additions and 0 deletions
@@ -0,0 +1,57 @@
+## ADDED Requirements
+
+### Requirement: Durable Metadata Store
+
+The platform SHALL support a configurable durable metadata store so platform resources survive process restarts without relying on in-memory maps.
+
+#### Scenario: File-backed platform metadata survives restart
+
+- **GIVEN** the platform is configured with the file storage backend and a metadata file path
+- **WHEN** users, server instances, jobs, artifacts, log streams, or other platform resources are created or updated
+- **THEN** the metadata SHALL be persisted to disk
+- **AND** recreating the store from the same file SHALL restore those resources.
+
+#### Scenario: Memory backend remains available for tests
+
+- **GIVEN** tests or development code explicitly request the memory backend
+- **WHEN** the platform creates a store
+- **THEN** it SHALL use the existing in-memory repository behavior without filesystem persistence.
+
+#### Scenario: Startup seeds local admin once
+
+- **GIVEN** durable metadata already contains the local platform administrator
+- **WHEN** the platform starts again
+- **THEN** startup seeding SHALL be idempotent and SHALL NOT overwrite the existing user.
+
+### Requirement: Segmented Log Body Storage
+
+The platform SHALL store high-volume log bodies in an append-friendly segmented log store instead of relying on in-memory maps or a row-per-log-line metadata database.
+
+#### Scenario: Log ingest persists entries durably
+
+- **GIVEN** a valid contiguous log batch for an existing stream
+- **WHEN** the platform accepts the batch
+- **THEN** the log body entries SHALL be written to the configured log body store before the stream latest sequence is advanced.
+
+#### Scenario: Duplicate batch detection survives reload
+
+- **GIVEN** a log batch has already been accepted and the platform restarts
+- **WHEN** the same batch is submitted again
+- **THEN** the platform SHALL return a duplicate acknowledgement when the first sequence, last sequence, and checksum match.
+
+#### Scenario: Cursor query stays bounded
+
+- **GIVEN** a log stream has many persisted entries
+- **WHEN** a client queries after a sequence with a limit
+- **THEN** the platform SHALL return at most the requested bounded number of entries ordered by sequence
+- **AND** SHALL include next and latest sequence metadata.
+
+### Requirement: Storage Backend Boundaries
+
+The platform SHALL separate metadata storage from log body storage and SHALL NOT expose storage paths, database credentials, run sockets, or raw credentials through API responses.
+
+#### Scenario: Storage details remain platform-owned
+
+- **GIVEN** plugins or frontend clients request platform resources, logs, artifacts, or bridge actions
+- **WHEN** responses are generated
+- **THEN** they SHALL include only bounded DTO data and SHALL NOT include filesystem paths, database DSNs, direct storage backend URLs, run session tokens, or bearer tokens.